@mininglamp-oss/cc-channel-octo 1.0.3-dev.1340db7 → 1.0.3-dev.1465991

package/dist/group-md-events.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GROUP.md server-event classification (P2-B) — event-driven cache refresh.
+ *
+ * The server emits system events on the inbound socket as `payload.event`
+ * (shape `{ type, version, updated_by, group_no, short_id }`, see
+ * octo/types.ts MessagePayload.event). When the operator edits a group's
+ * server GROUP.md, the server reports it as one of these events; on receipt we
+ * INVALIDATE the in-memory GROUP.md cache for that group so the next turn
+ * re-fetches the authoritative copy (see group-md-cache.ts `invalidate`).
+ *
+ * SECURITY — why invalidate-then-refetch, never trust the event payload:
+ *   The event arrives over the same untrusted channel as chat, so a forged
+ *   `group_md_updated` event must NOT be able to inject content. We never read
+ *   the new GROUP.md from the event body; we only use it as a signal to drop
+ *   the cached entry, after which the resolver re-fetches over the
+ *   authenticated bot token against the SSRF-validated apiUrl (the sole trusted
+ *   path, identical to P2-A). The worst a forged event can do is force a
+ *   redundant authenticated re-fetch of the real value — never poisoning.
+ *
+ * ⚠️ PROVISIONAL EVENT TYPE — the exact `event.type` literal the server emits
+ * for a GROUP.md change is NOT yet confirmed from a real captured event
+ * (XIN-173 confirmed the event SHAPE, not the type literal). The default below
+ * is named after the design (`group_md_updated`) and is overridable via
+ * `config.serverMdEventTypes`, so the literal can be calibrated against a real
+ * event WITHOUT a code change once captured. Keep this note until calibrated.
+ */
+/**
+ * Provisional `event.type` literals treated as a GROUP.md change. PROVISIONAL —
+ * see the calibration note above. Overridable via `config.serverMdEventTypes`.
+ */
+export declare const DEFAULT_GROUP_MD_EVENT_TYPES: readonly string[];
+/** The `payload.event` shape (mirrors MessagePayload.event in octo/types.ts). */
+export interface GroupMdEventLike {
+    type?: string;
+    group_no?: string;
+}
+/**
+ * True iff this event signals a GROUP.md change and should drive a cache
+ * refresh. All other system events (group join/leave, etc.) return false and
+ * are dropped unchanged by the router. `eventTypes` lets the operator override
+ * the provisional literal(s) without a code change.
+ */
+export declare function isGroupMdUpdateEvent(event: GroupMdEventLike | undefined, eventTypes?: readonly string[]): boolean;

package/dist/group-md-events.js

@@ -0,0 +1,43 @@
+/**
+ * GROUP.md server-event classification (P2-B) — event-driven cache refresh.
+ *
+ * The server emits system events on the inbound socket as `payload.event`
+ * (shape `{ type, version, updated_by, group_no, short_id }`, see
+ * octo/types.ts MessagePayload.event). When the operator edits a group's
+ * server GROUP.md, the server reports it as one of these events; on receipt we
+ * INVALIDATE the in-memory GROUP.md cache for that group so the next turn
+ * re-fetches the authoritative copy (see group-md-cache.ts `invalidate`).
+ *
+ * SECURITY — why invalidate-then-refetch, never trust the event payload:
+ *   The event arrives over the same untrusted channel as chat, so a forged
+ *   `group_md_updated` event must NOT be able to inject content. We never read
+ *   the new GROUP.md from the event body; we only use it as a signal to drop
+ *   the cached entry, after which the resolver re-fetches over the
+ *   authenticated bot token against the SSRF-validated apiUrl (the sole trusted
+ *   path, identical to P2-A). The worst a forged event can do is force a
+ *   redundant authenticated re-fetch of the real value — never poisoning.
+ *
+ * ⚠️ PROVISIONAL EVENT TYPE — the exact `event.type` literal the server emits
+ * for a GROUP.md change is NOT yet confirmed from a real captured event
+ * (XIN-173 confirmed the event SHAPE, not the type literal). The default below
+ * is named after the design (`group_md_updated`) and is overridable via
+ * `config.serverMdEventTypes`, so the literal can be calibrated against a real
+ * event WITHOUT a code change once captured. Keep this note until calibrated.
+ */
+/**
+ * Provisional `event.type` literals treated as a GROUP.md change. PROVISIONAL —
+ * see the calibration note above. Overridable via `config.serverMdEventTypes`.
+ */
+export const DEFAULT_GROUP_MD_EVENT_TYPES = ['group_md_updated'];
+/**
+ * True iff this event signals a GROUP.md change and should drive a cache
+ * refresh. All other system events (group join/leave, etc.) return false and
+ * are dropped unchanged by the router. `eventTypes` lets the operator override
+ * the provisional literal(s) without a code change.
+ */
+export function isGroupMdUpdateEvent(event, eventTypes = DEFAULT_GROUP_MD_EVENT_TYPES) {
+    if (!event || typeof event.type !== 'string' || event.type === '')
+        return false;
+    return eventTypes.includes(event.type);
+}
+//# sourceMappingURL=group-md-events.js.map

package/dist/group-md-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-md-events.js","sourceRoot":"","sources":["../src/group-md-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB,CAAC,kBAAkB,CAAC,CAAC;AAQpF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAmC,EACnC,aAAgC,4BAA4B;IAE5D,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAChF,OAAO,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC"}

package/dist/group-md-tool.d.ts

@@ -0,0 +1,49 @@
+/**
+ * P2-C: GROUP.md write-back tool — an in-process MCP server letting the agent
+ * persist an updated GROUP.md back to the server. The tool surfaces to the model
+ * as `mcp__group_md__update_group_md`.
+ *
+ * The server is built PER TURN (`createGroupMdToolServer`) with the current
+ * message's channel coords + the bot owner uid, so:
+ *  - the write targets the PARENT group of the channel the agent is in
+ *    (`extractParentGroupNo` — a thread shares its parent group's GROUP.md);
+ *  - invocation is GATED to the bot owner (registerBot.owner_uid). The group's
+ *    octo_tag token has server-side write permission, but the agent is driven by
+ *    untrusted IM users, so this owner gate — not LLM judgment, and independent
+ *    of the token's group-role permission — is what stops a prompt-injected
+ *    agent from rewriting the operator's trusted GROUP.md from any chat.
+ *
+ * Concurrency, the byte ceiling, and the cache refresh are owned by the shared
+ * {@link GroupMdWriteback} coordinator (group-md-writeback.ts); this layer is
+ * only the owner-gate policy + the MCP surface.
+ */
+import { z } from 'zod';
+import { type GroupMdWriteback } from './group-md-writeback.js';
+/** MCP server name; the tool surfaces as `mcp__group_md__update_group_md`. */
+export declare const GROUP_MD_TOOL_SERVER_NAME = "group_md";
+/** Raw coords of the session invoking the tool — gates the call + targets the group. */
+export interface GroupMdSessionCoords {
+    /** Full channelId (may be a `<groupNo>____<shortId>` thread composite). */
+    channelId: string;
+    fromUid: string;
+    fromName?: string;
+}
+/** Shared deps the tool needs to perform a write-back. */
+export interface GroupMdToolDeps {
+    writeback: GroupMdWriteback;
+    apiUrl: string;
+    botToken: string;
+}
+/**
+ * Build the GROUP.md tool DEFINITIONS for one agent turn. Exported separately
+ * from the server so tests can invoke the handler directly. `coords` targets the
+ * group + supplies the caller uid; `ownerUid` is the owner gate.
+ */
+export declare function buildGroupMdTools(deps: GroupMdToolDeps, coords: GroupMdSessionCoords, ownerUid: string): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    content: z.ZodString;
+}>[];
+/**
+ * Build the GROUP.md write-back MCP server for one agent turn. `coords` targets
+ * the group + supplies the caller uid; `ownerUid` is the owner gate.
+ */
+export declare function createGroupMdToolServer(deps: GroupMdToolDeps, coords: GroupMdSessionCoords, ownerUid: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/group-md-tool.js

@@ -0,0 +1,95 @@
+/**
+ * P2-C: GROUP.md write-back tool — an in-process MCP server letting the agent
+ * persist an updated GROUP.md back to the server. The tool surfaces to the model
+ * as `mcp__group_md__update_group_md`.
+ *
+ * The server is built PER TURN (`createGroupMdToolServer`) with the current
+ * message's channel coords + the bot owner uid, so:
+ *  - the write targets the PARENT group of the channel the agent is in
+ *    (`extractParentGroupNo` — a thread shares its parent group's GROUP.md);
+ *  - invocation is GATED to the bot owner (registerBot.owner_uid). The group's
+ *    octo_tag token has server-side write permission, but the agent is driven by
+ *    untrusted IM users, so this owner gate — not LLM judgment, and independent
+ *    of the token's group-role permission — is what stops a prompt-injected
+ *    agent from rewriting the operator's trusted GROUP.md from any chat.
+ *
+ * Concurrency, the byte ceiling, and the cache refresh are owned by the shared
+ * {@link GroupMdWriteback} coordinator (group-md-writeback.ts); this layer is
+ * only the owner-gate policy + the MCP surface.
+ */
+import { z } from 'zod';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { extractParentGroupNo } from './octo/channel-id.js';
+import { GroupMdContentTooLargeError, MAX_GROUP_MD_CONTENT_BYTES, } from './group-md-writeback.js';
+/** MCP server name; the tool surfaces as `mcp__group_md__update_group_md`. */
+export const GROUP_MD_TOOL_SERVER_NAME = 'group_md';
+function jsonResult(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+function errResult(msg) {
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}
+/**
+ * Build the GROUP.md tool DEFINITIONS for one agent turn. Exported separately
+ * from the server so tests can invoke the handler directly. `coords` targets the
+ * group + supplies the caller uid; `ownerUid` is the owner gate.
+ */
+export function buildGroupMdTools(deps, coords, ownerUid) {
+    const isOwner = coords.fromUid === ownerUid && ownerUid !== '';
+    return [
+        tool('update_group_md', 'Persist new GROUP.md content for THIS group on the server (it becomes the ' +
+            "group's trusted operator instructions on the next turn). `content` is the " +
+            'FULL replacement document, not a diff. Hard limit: 10240 bytes UTF-8. Only ' +
+            'the bot owner may call this; a non-owner request is rejected. Last write ' +
+            'wins server-side — compose the complete updated document, do not assume a ' +
+            'concurrent edit merged.', {
+            content: z
+                .string()
+                .describe('Full replacement GROUP.md document (≤10240 bytes UTF-8).'),
+        }, async (args) => {
+            try {
+                if (!isOwner) {
+                    return errResult('Only the bot owner can update GROUP.md.');
+                }
+                const groupNo = extractParentGroupNo(coords.channelId);
+                if (!groupNo) {
+                    return errResult('Could not resolve a group number from this channel.');
+                }
+                // Surface a friendly over-limit message before the coordinator throws
+                // (it re-checks as the authoritative boundary; this is just for UX).
+                const bytes = Buffer.byteLength(args.content, 'utf-8');
+                if (bytes > MAX_GROUP_MD_CONTENT_BYTES) {
+                    return errResult(`content is ${bytes} bytes, over the ${MAX_GROUP_MD_CONTENT_BYTES}-byte ` +
+                        `UTF-8 limit — trim it before writing (the server would reject it).`);
+                }
+                const res = await deps.writeback.writeBack({
+                    apiUrl: deps.apiUrl,
+                    botToken: deps.botToken,
+                    groupNo,
+                    content: args.content,
+                });
+                return jsonResult({
+                    updated: { groupNo: res.groupNo, version: res.version, bytes: res.bytes },
+                });
+            }
+            catch (err) {
+                if (err instanceof GroupMdContentTooLargeError) {
+                    return errResult(`content is ${err.bytes} bytes, over the ${MAX_GROUP_MD_CONTENT_BYTES}-byte UTF-8 limit.`);
+                }
+                return errResult(err instanceof Error ? err.message : String(err));
+            }
+        }),
+    ];
+}
+/**
+ * Build the GROUP.md write-back MCP server for one agent turn. `coords` targets
+ * the group + supplies the caller uid; `ownerUid` is the owner gate.
+ */
+export function createGroupMdToolServer(deps, coords, ownerUid) {
+    return createSdkMcpServer({
+        name: GROUP_MD_TOOL_SERVER_NAME,
+        version: '1.0.0',
+        tools: buildGroupMdTools(deps, coords, ownerUid),
+    });
+}
+//# sourceMappingURL=group-md-tool.js.map

package/dist/group-md-tool.js.map

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

package/dist/group-md-writeback.d.ts

@@ -0,0 +1,97 @@
+/**
+ * GROUP.md write-back (P2-C): the app-layer coordinator that persists an
+ * agent-authored GROUP.md back to the server (PUT /v1/bot/groups/{groupNo}/md)
+ * via A's `updateGroupMd` client, then refreshes A's in-memory cache so the next
+ * resolve does not TTL-refetch a stale copy.
+ *
+ * Two server-contract facts (XIN-201, measured — NOT inferred) shape this:
+ *
+ *   1. content has a HARD ≤10240-byte (UTF-8) limit; the server answers an
+ *      oversized body with 400 err.server.bot_api.content_too_large. We reject
+ *      locally BEFORE the PUT so a too-large write never reaches the server.
+ *
+ *   2. `version` is a server-side monotonic counter and the PUT does NOT do
+ *      compare-and-swap (last-write-wins, no CAS). Concurrent writers therefore
+ *      silently clobber each other server-side. We cannot fix a foreign writer
+ *      (operator console, another gateway), but we CAN guarantee that this
+ *      gateway never races itself: all write-backs for the same groupNo are
+ *      serialized through a per-groupNo promise-chain lock, so the read-modify-
+ *      write (PUT + cache update) for one call completes before the next starts.
+ *      Cross-source last-write-wins remains possible by design — see the caveat
+ *      on {@link GroupMdWriteback}.
+ *
+ * Owner-gating lives in the MCP tool layer (group-md-tool.ts), not here: this
+ * module is the mechanism, the tool is the policy boundary.
+ *
+ * Never persists anything to disk — the cache it updates is the same in-memory-
+ * only cache A's resolver reads (group-md-cache.ts), so this introduces no new
+ * durable-trust surface.
+ */
+import { updateGroupMd } from './octo/api.js';
+import type { GroupMdCache } from './group-md-cache.js';
+/**
+ * Hard UTF-8 byte ceiling for GROUP.md content, per the XIN-201 measured
+ * server contract. A body above this is rejected locally (a server PUT would
+ * answer 400 err.server.bot_api.content_too_large).
+ */
+export declare const MAX_GROUP_MD_CONTENT_BYTES = 10240;
+/** Thrown when content exceeds {@link MAX_GROUP_MD_CONTENT_BYTES}. */
+export declare class GroupMdContentTooLargeError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+/** The `updateGroupMd` client signature, injectable for testing. */
+export type UpdateGroupMdFn = typeof updateGroupMd;
+/** Outcome of a successful write-back. */
+export interface GroupMdWriteResult {
+    groupNo: string;
+    /** Server-assigned version after the PUT. */
+    version: number;
+    /** UTF-8 byte length of the content that was written. */
+    bytes: number;
+}
+export interface GroupMdWriteParams {
+    apiUrl: string;
+    botToken: string;
+    groupNo: string;
+    content: string;
+    signal?: AbortSignal;
+}
+/**
+ * Serializes GROUP.md write-backs per groupNo and keeps A's cache in sync.
+ *
+ * Constructed ONCE per bot (alongside the GroupMdCache it updates) and shared
+ * across turns, so the per-groupNo lock actually spans concurrent agent turns —
+ * a per-turn instance would defeat the lock. The MCP tool server (built per
+ * turn) borrows this shared instance.
+ *
+ * CAVEAT (documented per XIN-201 item 4): the lock only covers THIS gateway. A
+ * write from another source (operator console, a second gateway process) is not
+ * coordinated and, because the server has no CAS, last-write-wins across sources
+ * — that is an accepted limitation, not a bug.
+ */
+export declare class GroupMdWriteback {
+    private readonly cache;
+    /** Injectable PUT client (defaults to the real octo client). */
+    private readonly updateFn;
+    /** Tail of the in-flight write chain per groupNo (serializes same-key writes). */
+    private readonly tails;
+    constructor(cache: GroupMdCache, 
+    /** Injectable PUT client (defaults to the real octo client). */
+    updateFn?: UpdateGroupMdFn);
+    /**
+     * Run `fn` after every previously-queued op for `key` has settled, so bodies
+     * for the same key never overlap. Different keys run independently. `fn`'s
+     * rejection is surfaced to its own caller; the chain tail swallows it so a
+     * failed write does not wedge later writes.
+     */
+    private withLock;
+    /**
+     * Persist `content` as the group's GROUP.md and refresh the cache.
+     *
+     * Rejects with {@link GroupMdContentTooLargeError} (before any server call)
+     * when content exceeds the UTF-8 byte limit; propagates the client error when
+     * the PUT itself fails (cache is left untouched in that case).
+     */
+    writeBack(params: GroupMdWriteParams): Promise<GroupMdWriteResult>;
+}

package/dist/group-md-writeback.js

@@ -0,0 +1,118 @@
+/**
+ * GROUP.md write-back (P2-C): the app-layer coordinator that persists an
+ * agent-authored GROUP.md back to the server (PUT /v1/bot/groups/{groupNo}/md)
+ * via A's `updateGroupMd` client, then refreshes A's in-memory cache so the next
+ * resolve does not TTL-refetch a stale copy.
+ *
+ * Two server-contract facts (XIN-201, measured — NOT inferred) shape this:
+ *
+ *   1. content has a HARD ≤10240-byte (UTF-8) limit; the server answers an
+ *      oversized body with 400 err.server.bot_api.content_too_large. We reject
+ *      locally BEFORE the PUT so a too-large write never reaches the server.
+ *
+ *   2. `version` is a server-side monotonic counter and the PUT does NOT do
+ *      compare-and-swap (last-write-wins, no CAS). Concurrent writers therefore
+ *      silently clobber each other server-side. We cannot fix a foreign writer
+ *      (operator console, another gateway), but we CAN guarantee that this
+ *      gateway never races itself: all write-backs for the same groupNo are
+ *      serialized through a per-groupNo promise-chain lock, so the read-modify-
+ *      write (PUT + cache update) for one call completes before the next starts.
+ *      Cross-source last-write-wins remains possible by design — see the caveat
+ *      on {@link GroupMdWriteback}.
+ *
+ * Owner-gating lives in the MCP tool layer (group-md-tool.ts), not here: this
+ * module is the mechanism, the tool is the policy boundary.
+ *
+ * Never persists anything to disk — the cache it updates is the same in-memory-
+ * only cache A's resolver reads (group-md-cache.ts), so this introduces no new
+ * durable-trust surface.
+ */
+import { updateGroupMd } from './octo/api.js';
+/**
+ * Hard UTF-8 byte ceiling for GROUP.md content, per the XIN-201 measured
+ * server contract. A body above this is rejected locally (a server PUT would
+ * answer 400 err.server.bot_api.content_too_large).
+ */
+export const MAX_GROUP_MD_CONTENT_BYTES = 10240;
+/** Thrown when content exceeds {@link MAX_GROUP_MD_CONTENT_BYTES}. */
+export class GroupMdContentTooLargeError extends Error {
+    bytes;
+    constructor(bytes) {
+        super(`GROUP.md content is ${bytes} bytes, over the ${MAX_GROUP_MD_CONTENT_BYTES}-byte UTF-8 limit`);
+        this.bytes = bytes;
+        this.name = 'GroupMdContentTooLargeError';
+    }
+}
+/**
+ * Serializes GROUP.md write-backs per groupNo and keeps A's cache in sync.
+ *
+ * Constructed ONCE per bot (alongside the GroupMdCache it updates) and shared
+ * across turns, so the per-groupNo lock actually spans concurrent agent turns —
+ * a per-turn instance would defeat the lock. The MCP tool server (built per
+ * turn) borrows this shared instance.
+ *
+ * CAVEAT (documented per XIN-201 item 4): the lock only covers THIS gateway. A
+ * write from another source (operator console, a second gateway process) is not
+ * coordinated and, because the server has no CAS, last-write-wins across sources
+ * — that is an accepted limitation, not a bug.
+ */
+export class GroupMdWriteback {
+    cache;
+    updateFn;
+    /** Tail of the in-flight write chain per groupNo (serializes same-key writes). */
+    tails = new Map();
+    constructor(cache, 
+    /** Injectable PUT client (defaults to the real octo client). */
+    updateFn = updateGroupMd) {
+        this.cache = cache;
+        this.updateFn = updateFn;
+    }
+    /**
+     * Run `fn` after every previously-queued op for `key` has settled, so bodies
+     * for the same key never overlap. Different keys run independently. `fn`'s
+     * rejection is surfaced to its own caller; the chain tail swallows it so a
+     * failed write does not wedge later writes.
+     */
+    withLock(key, fn) {
+        const prev = this.tails.get(key) ?? Promise.resolve();
+        const result = prev.then(fn, fn); // run regardless of prior success/failure
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(key, tail);
+        // Best-effort cleanup: drop the key once the queue drains to this tail, so
+        // the Map does not grow without bound across many groups.
+        tail.then(() => {
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        });
+        return result;
+    }
+    /**
+     * Persist `content` as the group's GROUP.md and refresh the cache.
+     *
+     * Rejects with {@link GroupMdContentTooLargeError} (before any server call)
+     * when content exceeds the UTF-8 byte limit; propagates the client error when
+     * the PUT itself fails (cache is left untouched in that case).
+     */
+    async writeBack(params) {
+        const { apiUrl, botToken, groupNo, content, signal } = params;
+        const bytes = Buffer.byteLength(content, 'utf-8');
+        if (bytes > MAX_GROUP_MD_CONTENT_BYTES) {
+            // Reject locally — do NOT hit the server (it would answer 400).
+            throw new GroupMdContentTooLargeError(bytes);
+        }
+        return this.withLock(groupNo, async () => {
+            const { version } = await this.updateFn({ apiUrl, botToken, groupNo, content, signal });
+            // Write the just-persisted content/version back into A's in-memory cache
+            // so the next resolveGroupInstructions serves what we wrote instead of
+            // either re-fetching (TTL) or, worse, returning a now-stale cached copy.
+            // updated_at is null because the PUT response carries only { version }.
+            this.cache.set(groupNo, {
+                content,
+                version: typeof version === 'number' ? version : 0,
+                updated_at: null,
+            });
+            return { groupNo, version, bytes };
+        });
+    }
+}
+//# sourceMappingURL=group-md-writeback.js.map

package/dist/group-md-writeback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-md-writeback.js","sourceRoot":"","sources":["../src/group-md-writeback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD,sEAAsE;AACtE,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACxB;IAA5B,YAA4B,KAAa;QACvC,KAAK,CACH,uBAAuB,KAAK,oBAAoB,0BAA0B,mBAAmB,CAC9F,CAAC;QAHwB,UAAK,GAAL,KAAK,CAAQ;QAIvC,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAsBD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,gBAAgB;IAKR;IAEA;IANnB,kFAAkF;IACjE,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE7D,YACmB,KAAmB;IACpC,gEAAgE;IAC/C,WAA4B,aAAa;QAFzC,UAAK,GAAL,KAAK,CAAc;QAEnB,aAAQ,GAAR,QAAQ,CAAiC;IACzD,CAAC;IAEJ;;;;;OAKG;IACK,QAAQ,CAAI,GAAW,EAAE,EAAoB;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,0CAA0C;QAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CACtB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,2EAA2E;QAC3E,0DAA0D;QAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACb,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,MAA0B;QACxC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,KAAK,GAAG,0BAA0B,EAAE,CAAC;YACvC,gEAAgE;YAChE,MAAM,IAAI,2BAA2B,CAAC,KAAK,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACxF,yEAAyE;YACzE,uEAAuE;YACvE,yEAAyE;YACzE,wEAAwE;YACxE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE;gBACtB,OAAO;gBACP,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAClD,UAAU,EAAE,IAAI;aACjB,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/group-md.d.ts

@@ -0,0 +1,53 @@
+/**
+ * GROUP.md resolution (P2-A): server-first fetch with a never-lose local-file
+ * fallback, behind a feature flag.
+ *
+ * `resolveGroupInstructions` is the single entry point the message pipeline
+ * calls to obtain the trusted per-group instruction block injected into the
+ * agent's system prompt. Resolution order:
+ *
+ *   1. Feature flag OFF (default) or no cache wired → pure local file
+ *      (`loadGroupConfig`). Byte-identical to the pre-P2 behavior, so existing
+ *      local-file deployments are unaffected.
+ *   2. Feature flag ON:
+ *        a. serve a cached server GROUP.md if present and not past its TTL (keyed
+ *           by the PARENT group number — a thread shares its parent group's
+ *           GROUP.md). The cache is IN-MEMORY ONLY (no disk), so the only way
+ *           content reaches this trusted system-prompt channel is a live,
+ *           authenticated fetch — never a forgeable on-disk artifact a chat-
+ *           driven Bash/Write could plant (review #172 🔴; see group-md-cache.ts);
+ *        b. otherwise fetch from the server (server-first). On success with
+ *           non-empty content, cache it and use it;
+ *        c. on ANY failure (404 "no GROUP.md", network, timeout, empty content)
+ *           fall back to the local file. The local-file path is never lost.
+ *
+ * Trust: server content stands on its own trust root — an authenticated
+ * `getGroupMd` over the bot token against the SSRF-validated `apiUrl`, server-
+ * side bot_admin-gated — NOT on the OS-permission trust the local `groupConfigDir`
+ * file relies on. By caching only in memory we never let server content
+ * masquerade as (or be confused with) a trusted local file on disk.
+ *
+ * Thread routing (P1): a thread channelId is the composite `<groupNo>____<shortId>`.
+ * The server GROUP.md endpoint is keyed by the parent group number, so we resolve
+ * it with `extractParentGroupNo` for the API call + cache key (identity for a
+ * plain group). The local-file fallback still receives the FULL channelId so its
+ * own thread/short-id routing in `loadGroupConfig` is preserved unchanged.
+ *
+ * Never throws — a server error degrades to local, a local miss degrades to
+ * "no custom instructions".
+ */
+import type { GroupMdCache } from './group-md-cache.js';
+export interface ResolveGroupInstructionsParams {
+    /** Operator local-instruction directory (the existing fallback source). */
+    groupConfigDir?: string;
+    /** Feature flag: when false/undefined, server fetch is skipped entirely. */
+    serverMd?: boolean;
+    apiUrl: string;
+    botToken: string;
+    /** Full channelId (may be a `<groupNo>____<shortId>` thread composite). */
+    channelId: string;
+    /** Server GROUP.md cache. Omitted (or flag off) → pure local file. */
+    cache?: GroupMdCache;
+    signal?: AbortSignal;
+}
+export declare function resolveGroupInstructions(params: ResolveGroupInstructionsParams): Promise<string | undefined>;

package/dist/group-md.js

@@ -0,0 +1,98 @@
+/**
+ * GROUP.md resolution (P2-A): server-first fetch with a never-lose local-file
+ * fallback, behind a feature flag.
+ *
+ * `resolveGroupInstructions` is the single entry point the message pipeline
+ * calls to obtain the trusted per-group instruction block injected into the
+ * agent's system prompt. Resolution order:
+ *
+ *   1. Feature flag OFF (default) or no cache wired → pure local file
+ *      (`loadGroupConfig`). Byte-identical to the pre-P2 behavior, so existing
+ *      local-file deployments are unaffected.
+ *   2. Feature flag ON:
+ *        a. serve a cached server GROUP.md if present and not past its TTL (keyed
+ *           by the PARENT group number — a thread shares its parent group's
+ *           GROUP.md). The cache is IN-MEMORY ONLY (no disk), so the only way
+ *           content reaches this trusted system-prompt channel is a live,
+ *           authenticated fetch — never a forgeable on-disk artifact a chat-
+ *           driven Bash/Write could plant (review #172 🔴; see group-md-cache.ts);
+ *        b. otherwise fetch from the server (server-first). On success with
+ *           non-empty content, cache it and use it;
+ *        c. on ANY failure (404 "no GROUP.md", network, timeout, empty content)
+ *           fall back to the local file. The local-file path is never lost.
+ *
+ * Trust: server content stands on its own trust root — an authenticated
+ * `getGroupMd` over the bot token against the SSRF-validated `apiUrl`, server-
+ * side bot_admin-gated — NOT on the OS-permission trust the local `groupConfigDir`
+ * file relies on. By caching only in memory we never let server content
+ * masquerade as (or be confused with) a trusted local file on disk.
+ *
+ * Thread routing (P1): a thread channelId is the composite `<groupNo>____<shortId>`.
+ * The server GROUP.md endpoint is keyed by the parent group number, so we resolve
+ * it with `extractParentGroupNo` for the API call + cache key (identity for a
+ * plain group). The local-file fallback still receives the FULL channelId so its
+ * own thread/short-id routing in `loadGroupConfig` is preserved unchanged.
+ *
+ * Never throws — a server error degrades to local, a local miss degrades to
+ * "no custom instructions".
+ */
+import { getGroupMd } from './octo/api.js';
+import { extractParentGroupNo } from './octo/channel-id.js';
+import { loadGroupConfig, MAX_GROUP_CONFIG_BYTES } from './group-config.js';
+/**
+ * Trim and byte-bound server-provided GROUP.md the same way loadGroupConfig
+ * bounds a local file, so an oversized server payload can't blow the prompt
+ * budget. Returns undefined for empty/whitespace-only content.
+ */
+function boundInstructions(content) {
+    let text = content;
+    if (Buffer.byteLength(text, 'utf-8') > MAX_GROUP_CONFIG_BYTES) {
+        const buf = Buffer.from(text, 'utf-8').subarray(0, MAX_GROUP_CONFIG_BYTES);
+        // The slice may end mid-codepoint; trim a trailing replacement char.
+        text = buf.toString('utf-8').replace(/�+$/, '') + '\n[… group config truncated]';
+    }
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export async function resolveGroupInstructions(params) {
+    const { groupConfigDir, serverMd, apiUrl, botToken, channelId, cache, signal } = params;
+    const local = () => loadGroupConfig(groupConfigDir, channelId);
+    // Flag off (or no cache to dedupe fetches) → pure local file, unchanged behavior.
+    if (!serverMd || !cache)
+        return local();
+    const groupNo = extractParentGroupNo(channelId);
+    // a) fresh cached server GROUP.md wins. The cache is in-memory only and TTL-
+    //    bounded, so an expired entry reads as a miss and falls through to a
+    //    re-fetch below (staleness backstop; item B adds event-driven refresh).
+    const cached = cache.get(groupNo);
+    if (cached) {
+        const bounded = boundInstructions(cached.content);
+        if (bounded)
+            return bounded;
+        // Cached-but-empty (shouldn't normally happen) → fall through to local.
+        return local();
+    }
+    // b) server-first fetch.
+    try {
+        const md = await getGroupMd({ apiUrl, botToken, groupNo, signal });
+        const bounded = boundInstructions(md?.content ?? '');
+        if (bounded) {
+            const entry = {
+                content: md.content,
+                version: typeof md.version === 'number' ? md.version : 0,
+                updated_at: md.updated_at ?? null,
+                updated_by: md.updated_by,
+            };
+            cache.set(groupNo, entry);
+            return bounded;
+        }
+        // Server reachable but no/empty GROUP.md → local fallback.
+        return local();
+    }
+    catch (err) {
+        // c) 404 / network / timeout — never-lose local fallback.
+        console.error(`[cc-channel-octo] group-md: server fetch for ${groupNo} failed, falling back to local: ${String(err)}`);
+        return local();
+    }
+}
+//# sourceMappingURL=group-md.js.map

package/dist/group-md.js.map

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

package/dist/index.d.ts

@@ -13,6 +13,8 @@ import { SessionRouter } from './session-router.js';
 import { GroupContext } from './group-context.js';
 import { StreamRelay } from './stream-relay.js';
 import type { BotMessage } from './octo/types.js';
+import { GroupMdCache } from './group-md-cache.js';
+import { GroupMdWriteback } from './group-md-writeback.js';
 import { CronStore } from './cron-store.js';
 /**
  * Resolve a single bot's concrete Config by its configId (config.json
@@ -33,7 +35,7 @@ export type BotStack = ManagedBot;
  * agent query → stream → persist. Exported so tests can drive the real pipeline
  * (not a replica) — `main()` is the only production caller.
  */
-export declare function handleMessage(msg: BotMessage, config: ReturnType<typeof loadConfig>, store: SessionStore, router: SessionRouter, groupContext: GroupContext, streamRelay: StreamRelay, botId: string, cronStore?: CronStore): Promise<void>;
+export declare function handleMessage(msg: BotMessage, config: ReturnType<typeof loadConfig>, store: SessionStore, router: SessionRouter, groupContext: GroupContext, streamRelay: StreamRelay, botId: string, cronStore?: CronStore, groupMdCache?: GroupMdCache, groupMdWriteback?: GroupMdWriteback): Promise<void>;
 /** Max length of the rendered tool-params string in a 🔧 progress notice. */
 export declare const MAX_TOOL_PARAM_CHARS = 120;
 /**