@mininglamp-oss/cc-channel-octo 1.0.1

package/dist/commands.js

@@ -0,0 +1,121 @@
+/**
+ * In-chat slash commands (v0.3).
+ *
+ * Users can control their session without leaving the chat:
+ *   /reset            — clear this session's conversation history
+ *   /config           — show the effective per-session settings
+ *   /help             — list available commands
+ *
+ * Commands are matched on the FIRST line of the cleaned message text (after the
+ * router has stripped any leading @bot mention), so `@bot /reset` works in
+ * groups. Matching is case-insensitive and tolerant of surrounding whitespace.
+ *
+ * A command is scoped to the sessionKey of the message. In a group the session
+ * is shared per channel, so `/reset` clears the WHOLE group's conversation
+ * history (every member shares one session), not just the caller's. In a DM it
+ * clears that peer's history. Note: it does NOT clear long-term auto-memory.
+ *
+ * Note: commands are handled inside the router's processing callback, AFTER the
+ * per-session rate limit is applied. A user who has exhausted their token bucket
+ * therefore cannot run `/reset` or `/help` until it refills — control commands
+ * are rate-limited like normal messages. This is intentional (a flooder should
+ * not get a rate-limit bypass via slash commands); documented in the README.
+ */
+/** Not a command at all — let the normal agent pipeline take over. */
+const NOT_A_COMMAND = { handled: false };
+/**
+ * Parse the command token from a message body. Returns the lowercased command
+ * name (without the leading slash) and the trimmed argument string, or null
+ * when the text does not start with a slash command.
+ *
+ * Only the first whitespace-delimited token on the first line is considered, so
+ * a message that merely mentions "/reset" mid-sentence is NOT treated as a
+ * command — it must lead.
+ */
+export function parseCommand(body) {
+    const firstLine = body.split('\n', 1)[0]?.trim() ?? '';
+    // The command name must be followed by a TOKEN BOUNDARY — end-of-line or
+    // whitespace — before any args. Without this, path/route-like text such as
+    // `/reset/foo`, `/config.json`, or `/help.md` would be parsed as the bare
+    // command and could trigger a destructive action (`/reset`). Requiring `\s+`
+    // (or EOL) after the name means only a real command token matches; anything
+    // glued to the name (`/foo.bar`, `/a/b`) is NOT a command and falls through
+    // to the normal agent pipeline.
+    const match = firstLine.match(/^\/([a-zA-Z][a-zA-Z0-9_-]*)(?:\s+(.*))?$/);
+    if (!match)
+        return null;
+    return { name: match[1].toLowerCase(), args: (match[2] ?? '').trim() };
+}
+/** Human-readable list of supported commands. */
+const HELP_TEXT = [
+    'Available commands:',
+    '• `/reset` — clear the conversation history for this session (the whole group, in a group chat); does not clear long-term memory',
+    '• `/config` — show the current session settings',
+    '• `/help` — show this message',
+].join('\n');
+/**
+ * Render the effective, non-sensitive per-session configuration. Deliberately
+ * omits secrets (botToken, apiUrl host details beyond scheme) — this reply is
+ * visible to any user who can message the bot.
+ */
+function renderConfig(config) {
+    const tools = config.sdk.allowedTools === '*'
+        ? '* (all SDK tools)'
+        : config.sdk.allowedTools.join(', ');
+    return [
+        'Current settings:',
+        `• model: ${config.sdk.model ?? '(SDK default)'}`,
+        `• allowedTools: ${tools}`,
+        `• permissionMode: ${config.sdk.permissionMode}`,
+        `• rateLimit: ${config.rateLimit.maxPerMinute} req/min`,
+        `• historyLimit: ${config.context.historyLimit} messages`,
+    ].join('\n');
+}
+/**
+ * Try to handle `body` as a slash command for the given session.
+ *
+ * Returns `{ handled: false }` when the text is not a command (caller proceeds
+ * with the normal agent pipeline). When handled, returns the reply to send and
+ * performs any side effect (e.g. clearing history) immediately.
+ *
+ * `messageSeq` is the seq of the command message itself; `/reset` records it as
+ * a persisted barrier so cold-start group backfill cannot resurrect pre-reset
+ * history on a later turn.
+ */
+export function handleCommand(body, sessionKey, store, config, messageSeq) {
+    const parsed = parseCommand(body);
+    if (!parsed)
+        return NOT_A_COMMAND;
+    switch (parsed.name) {
+        case 'reset': {
+            // Scoped to THIS sessionKey. In a group the session is shared per channel,
+            // so this clears the whole group's conversation history; in a DM it clears
+            // that peer's. Long-term auto-memory (under memoryBase) is NOT cleared.
+            store.deleteSession(sessionKey);
+            // Persist a barrier at this message_seq so G4 cold-start backfill (which
+            // refetches channel history when the local cache is empty) cannot
+            // re-seed the history we just cleared — even across a process restart.
+            if (messageSeq !== undefined) {
+                store.setResetBarrier(sessionKey, messageSeq);
+            }
+            // v0.3 persistent sessions: also forget the SDK session id, otherwise the
+            // next turn would `resume` it and bring the just-cleared conversation back.
+            store.clearSdkSessionId(sessionKey);
+            return { handled: true, reply: '✓ Conversation history cleared (long-term memory is kept).' };
+        }
+        case 'config': {
+            return { handled: true, reply: renderConfig(config) };
+        }
+        case 'help': {
+            return { handled: true, reply: HELP_TEXT };
+        }
+        default:
+            // A leading-slash token we don't recognize. Report it rather than
+            // silently forwarding to the agent, so typos are visible.
+            return {
+                handled: true,
+                reply: `Unknown command: /${parsed.name}\n\n${HELP_TEXT}`,
+            };
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Configuration loading.
+ *
+ * Two-layer, bot-first model:
+ *  - GLOBAL `~/.cc-channel-octo/config.json` — shared defaults + a `bots` list.
+ *    Never holds a botToken.
+ *  - PER-BOT `~/.cc-channel-octo/<id>/config.json` — that bot's botToken + any
+ *    overrides. Each bot is a self-contained subtree:
+ *      <baseDir>/<id>/{config.json, SOUL.md, data/, workspace/, memory/}
+ *  - `baseDir` is the directory containing the global config.json. Per-bot dirs
+ *    are DERIVED from `<baseDir>/<id>/…` (not separately configurable) so a bot
+ *    can never point its data outside its own subtree.
+ *
+ * env overrides still apply to the shared/global layer.
+ */
+/**
+ * Default global config path: `~/.cc-channel-octo/config.json`. This is the
+ * single, fixed production location (no env/CLI override). Tests pass an
+ * explicit path, which also sets `baseDir` to that file's directory.
+ */
+export declare const DEFAULT_CONFIG_PATH: string;
+/**
+ * Q2: Wildcard form of `allowedTools` — `"*"` means "allow every tool the SDK
+ * exposes". Otherwise must be an explicit string array (whitelist mode).
+ */
+export type AllowedTools = string[] | '*';
+export interface Config {
+    botToken: string;
+    apiUrl: string;
+    /**
+     * Base directory containing the global config.json. Every bot's subtree lives
+     * at `<baseDir>/<botId>/…`. Defaults to `~/.cc-channel-octo` (the dir of
+     * DEFAULT_CONFIG_PATH); when an explicit config path is passed, it is that
+     * file's directory.
+     */
+    baseDir: string;
+    /**
+     * DERIVED (not user-configurable): per-session cwd sandbox base for THIS bot,
+     * `<baseDir>/<botId>/workspace`. Each (DM peer | group channel) gets its own
+     * hashed subdir under it via `cwd-resolver.resolveSessionCwd()`. Populated by
+     * `resolveBotConfigs()`.
+     */
+    cwdBase?: string;
+    /**
+     * @deprecated Alias of `cwdBase`, kept in sync so hand-built Config objects
+     * (tests, legacy consumers reading `config.cwd`) still compile.
+     */
+    cwd: string;
+    /**
+     * DERIVED (not user-configurable): SQLite/data dir for THIS bot,
+     * `<baseDir>/<botId>/data`. Populated by `resolveBotConfigs()`.
+     */
+    dataDir: string;
+    /**
+     * DERIVED (not user-configurable): SDK auto-memory base for THIS bot,
+     * `<baseDir>/<botId>/memory`. Each session gets a hashed subdir under it (same
+     * partitioning as the cwd sandbox: group=shared per channel, DM=private per
+     * peer). Separate from the cwd sandbox so the 7-day cwd TTL never reclaims
+     * memory. Populated by `resolveBotConfigs()`.
+     */
+    memoryBase?: string;
+    /**
+     * DERIVED (not user-configurable): per-bot skills directory,
+     * `<baseDir>/<botId>/skills`. Each immediate subdir is a Claude skill
+     * (`SKILL.md` + optional `references/`, `scripts/`). Symlinked into each
+     * session sandbox's `.claude/skills/` so the SDK discovers it (requires
+     * `sdk.settingSources` to include `project`). Per-bot skills override
+     * same-named global skills. Populated by `resolveBotConfigs()`.
+     */
+    skillsDir?: string;
+    /**
+     * DERIVED (not user-configurable): install-wide skills directory shared by all
+     * bots, `<baseDir>/skills`. Loaded for every bot (lower precedence than the
+     * per-bot `skillsDir`). Populated by `resolveBotConfigs()`.
+     */
+    globalSkillsDir?: string;
+    /**
+     * v1.0: directory of per-group instruction files (`<groupId>.md`). When set,
+     * a matching file's contents are injected into the system prompt as trusted
+     * custom instructions for that group. Operator-controlled — must NOT be the
+     * per-session cwd sandbox (which the agent can write). Unset = feature off.
+     */
+    groupConfigDir?: string;
+    sdk: {
+        model?: string;
+        /**
+         * Q2: `"*"` allows every tool the SDK exposes; otherwise an explicit
+         * whitelist. Default is `"*"` because we already control surface area via
+         * `permissionMode` and `cwdBase` isolation — the old hard-coded 8-tool
+         * list was redundant lockdown and broke operators who needed SDK-internal
+         * tools like `TodoWrite`/`Task`.
+         */
+        allowedTools: AllowedTools;
+        permissionMode: string;
+        maxTurns?: number;
+        systemPrompt?: string;
+        /**
+         * Which filesystem settings sources the SDK loads (`user`/`project`/`local`).
+         * Default is `['project']` so the SDK discovers skills symlinked into the
+         * session sandbox's `.claude/skills/` (#100 — generic external tooling).
+         *
+         * Memory isolation is preserved INDEPENDENTLY of this: the auto-memory
+         * directory is pinned via inline `settings.autoMemoryDirectory` (the SDK's
+         * `flagSettings` tier), which takes precedence over any `projectSettings`
+         * value — and the SDK explicitly ignores `autoMemoryDirectory` coming from a
+         * checked-in `projectSettings` for security. So `['project']` lets the bot
+         * read the sandbox `.claude/` (skills, and any CLAUDE.md/settings.json the
+         * agent itself wrote — acceptable, it's the agent's own workspace) WITHOUT
+         * the memory leaking into the host `~/.claude` (verified empirically).
+         *
+         * `'user'` would additionally load the operator's real `~/.claude` config —
+         * opt into that deliberately only. Note: this controls what is LOADED (read),
+         * not tool-write scope (governed by `permissionMode`/`allowedTools`).
+         */
+        settingSources: string[];
+        /**
+         * v0.3: when true, the bot sends brief "🔧 Running <tool>…" progress
+         * messages as the agent invokes tools, so users see activity during long
+         * tool-heavy turns. Default false — it adds extra chat messages, so it is
+         * opt-in. Env: `CC_OCTO_SDK_TOOL_PROGRESS=true`.
+         */
+        toolProgress?: boolean;
+        /**
+         * Q1: Override the upstream Claude API endpoint (e.g. self-hosted gateway).
+         * Forwarded to the SDK subprocess via the standard `ANTHROPIC_BASE_URL`
+         * environment variable.
+         */
+        anthropicBaseUrl?: string;
+        /**
+         * #107: extra environment variables injected verbatim into the agent's SDK
+         * subprocess (on top of the inherited process.env). Generic and declarative
+         * — cc knows nothing about what they mean. Use it to give a bot's skills the
+         * env their external CLIs need, e.g. `{ "OCTO_BOT_ID": "<robotId>" }` so a
+         * multi-bot deploy's `octo-cli` calls select the right stored profile.
+         * Per-bot (set in `<baseDir>/<id>/config.json`).
+         */
+        env?: Record<string, string>;
+        /**
+         * #110: which skills this bot enables, selecting a subset of the skills
+         * discovered in its session sandbox's `.claude/skills/` (the shared library
+         * `<baseDir>/skills` + per-bot `<baseDir>/<id>/skills`, symlinked in by the
+         * skill-linker). Names match each SKILL.md `name` / directory name.
+         *   - omitted: SDK default (no explicit selection).
+         *   - `'all'`: enable every discovered skill.
+         *   - `string[]`: enable only the listed skills.
+         * This is the per-bot SELECTION layer over the centrally-maintained library:
+         * maintain skills once, each bot picks its own subset. Per-bot (set in
+         * `<baseDir>/<id>/config.json`).
+         */
+        skills?: string[] | 'all';
+        /**
+         * #115: when true, give the agent a `cron` tool set (cron_create / cron_list
+         * / cron_delete) to register per-bot scheduled tasks, persisted to
+         * `<baseDir>/<botId>/cron.json` and fired by the gateway scheduler through
+         * the normal message pipeline (bound to the creating session). Task creation
+         * is gated to the bot owner uid (registerBot.owner_uid). Default off. Per-bot.
+         */
+        cron?: boolean;
+    };
+    rateLimit: {
+        maxPerMinute: number;
+    };
+    context: {
+        maxContextChars: number;
+        historyLimit: number;
+    };
+    /** Maximum response length in chars before truncation (Q32). */
+    maxResponseChars: number;
+    botBlocklist?: string[];
+    /**
+     * G14: Bots in this list are allowed to DM the bot even if their uid matches
+     * the `_bot` heuristic. Use this to whitelist trusted bots.
+     */
+    allowedBotUids?: string[];
+    /** Group IDs where the bot responds without being @mentioned (G12). */
+    mentionFreeGroups?: string[];
+    /**
+     * v0.3 multi-bot: optional per-bot overrides. When present and non-empty, the
+     * process runs ONE independent bot per entry, each with its own gateway,
+     * router, store, and (by default) data directory — so bots never share history
+     * or working dirs. Each entry inherits every top-level field and overrides the
+     * listed ones; `botToken` is required per entry. When absent, the process runs
+     * a single bot from the top-level fields exactly as before.
+     *
+     * Resolved into concrete per-bot Config objects by `resolveBotConfigs()`.
+     */
+    bots?: BotOverride[];
+    /**
+     * v0.3 multi-bot: stable identifier for THIS bot, used to namespace its data
+     * directory and logs when running multiple bots. Defaults to `default` for the
+     * single-bot case. Populated by `resolveBotConfigs()`.
+     */
+    botId?: string;
+    /**
+     * #86: media CDN host (no scheme), prefetched at startup from the upload-
+     * credentials STS response (`cdnBaseUrl`). Octo serves media from a separate
+     * CDN host than `apiUrl`; inbound media URLs on this host are allowed by
+     * buildMediaUrl. Runtime-populated (not from the config file); undefined until
+     * the prefetch succeeds, in which case only same-apiUrl-host media is allowed.
+     */
+    mediaCdnHost?: string;
+}
+/**
+ * One bot's entry. In the two-layer model the global config's `bots` array
+ * lists which bots to run (by `id`); each bot's real settings — including its
+ * required `botToken` — live in `<baseDir>/<id>/config.json`, which is merged
+ * OVER both the global shared fields and any inline fields here (per-dir wins).
+ *
+ * Per-bot directories are NOT configurable here: they are always derived as
+ * `<baseDir>/<id>/{data,workspace,memory}` so a bot cannot escape its subtree.
+ */
+export interface BotOverride {
+    /**
+     * Stable id — also the bot's subtree name under `baseDir`. Required in the
+     * two-layer model (it selects `<baseDir>/<id>/config.json`). Must be a
+     * conservative slug: letters, digits, dot, underscore, hyphen — no path
+     * separators (it becomes a path segment).
+     */
+    id?: string;
+    /**
+     * Optional here — normally provided by the per-bot `<id>/config.json`. If set
+     * inline it is used unless the per-bot file overrides it.
+     */
+    botToken?: string;
+    apiUrl?: string;
+    model?: string;
+    systemPrompt?: string;
+    botBlocklist?: string[];
+    allowedBotUids?: string[];
+    mentionFreeGroups?: string[];
+}
+/**
+ * SSRF protection for apiUrl: implemented in url-policy.ts (isAllowedApiUrl).
+ * S6 fix: now rejects https://127.0.0.1 too — https doesn't make a private
+ * address safe (could be a self-signed mitmproxy).
+ */
+export declare function loadConfig(configPath?: string): Config;
+/**
+ * v0.3 multi-bot: expand a loaded Config into one concrete Config per bot.
+ *
+ * - Single-bot (no `bots`): returns `[config]` with `botId` defaulted to
+ *   `default`, unchanged otherwise — fully backward compatible.
+ * - Multi-bot: returns one Config per `bots[]` entry. Each inherits the base
+ *   config and applies its overrides. To guarantee bots never share history,
+ *   cwd, or lock files, each bot's `dataDir` and `cwdBase` are namespaced by its
+ *   id UNLESS the entry sets them explicitly.
+ *
+ * Throws on missing/duplicate bot tokens or duplicate ids (fail fast at boot).
+ */
+/**
+ * Expand a loaded GLOBAL config into one concrete Config per bot.
+ *
+ * Two-layer, bot-first model:
+ * - Single-bot (no `bots`): one bot with id `default`. Its token/overrides come
+ *   from the global config and/or `<baseDir>/default/config.json`.
+ * - Multi-bot: one Config per `bots[]` entry (selected by `id`). For each, the
+ *   effective config is: global shared fields ⊕ inline `bots[]` fields ⊕
+ *   `<baseDir>/<id>/config.json` (per-dir file wins).
+ *
+ * Every bot's directories are DERIVED (never configurable):
+ *   data      = <baseDir>/<id>/data
+ *   workspace = <baseDir>/<id>/workspace   (cwdBase)
+ *   memory    = <baseDir>/<id>/memory
+ * and its personality from `<baseDir>/<id>/SOUL.md` (overrides systemPrompt).
+ *
+ * Throws on missing/duplicate tokens, duplicate ids, invalid id slugs, or unsafe
+ * apiUrl (fail fast at boot).
+ */
+export declare function resolveBotConfigs(config: Config): Config[];
+/**
+ * v1.1: openclaw-style per-bot personality. Read `<botRoot>/SOUL.md` if it
+ * exists and return its trimmed contents as the bot's "soul" (voice/stance/
+ * boundaries), to be composed into the agent system prompt. Mirrors openclaw's
+ * SOUL.md: a file you edit, not a config string. When the file is absent or
+ * empty, returns undefined so the caller falls back to the `systemPrompt`
+ * config string. Best-effort — a read error never blocks startup.
+ */
+export declare function loadSoul(botRoot: string): string | undefined;