@mininglamp-oss/cc-channel-octo 1.0.3-dev.4ca07a0 → 1.0.3-dev.4edf363

package/dist/group-md-cache.js

@@ -90,4 +90,83 @@ export class GroupMdCache {
         this.mem.delete(groupNo);
     }
 }
+/**
+ * THREAD.md server cache (P3-1) — IN-MEMORY ONLY, with a TTL.
+ *
+ * The thread analogue of {@link GroupMdCache}. Holds server-fetched THREAD.md
+ * for a CommunityTopic thread. Same memory-only security model as the group
+ * cache (see the module SECURITY note): the resolved THREAD.md is injected as a
+ * trusted system-prompt block, so it must never touch disk — the only path
+ * content can enter the trusted channel is a live, authenticated `getThreadMd`
+ * over the bot token against the SSRF-validated `apiUrl`.
+ *
+ * Keying — COMPOSITE `<groupNo>::<shortId>`, NOT the bare shortId. Octo's
+ * current shortId is a globally unique 19-digit snowflake, so a bare shortId
+ * would not collide across groups today; the composite key is defensive
+ * double-insurance so that even if a future shortId scheme becomes a
+ * per-parent-group sequence, one group's THREAD.md can never be served for a
+ * same-shortId thread under a different parent group. `::` is intentionally
+ * outside the safe-id charset, so it can never appear inside a validated
+ * component and cannot be forged to cross a key boundary.
+ *
+ * Never throws.
+ */
+export class ThreadMdCache {
+    mem = new Map();
+    ttlMs;
+    now;
+    /**
+     * @param ttlMs staleness backstop in ms (entry expires this long after it was
+     *   stored). Defaults to {@link DEFAULT_GROUP_MD_TTL_MS} — the thread cache
+     *   shares the group cache's staleness policy. A non-positive value disables
+     *   expiry (entries live until invalidate()).
+     * @param now injectable clock (testing); defaults to Date.now.
+     */
+    constructor(ttlMs = DEFAULT_GROUP_MD_TTL_MS, now = () => Date.now()) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    /**
+     * Build the composite Map key, or null if either component is unsafe. Both
+     * halves are validated with the same isSafeGroupNo rule the group cache uses,
+     * and neither can contain `::` (colon is outside the charset), so the
+     * separator is unambiguous.
+     */
+    key(groupNo, shortId) {
+        if (!isSafeGroupNo(groupNo) || !isSafeGroupNo(shortId))
+            return null;
+        return `${groupNo}::${shortId}`;
+    }
+    /**
+     * Read a cached entry from memory. Returns undefined on a miss, an expired
+     * entry (which is also evicted), or an unsafe groupNo/shortId.
+     */
+    get(groupNo, shortId) {
+        const k = this.key(groupNo, shortId);
+        if (k === null)
+            return undefined;
+        const stored = this.mem.get(k);
+        if (!stored)
+            return undefined;
+        if (this.ttlMs > 0 && this.now() - stored.storedAt >= this.ttlMs) {
+            this.mem.delete(k);
+            return undefined;
+        }
+        return stored.entry;
+    }
+    /** Store an entry in memory, stamping it for TTL expiry. */
+    set(groupNo, shortId, entry) {
+        const k = this.key(groupNo, shortId);
+        if (k === null)
+            return;
+        this.mem.set(k, { entry, storedAt: this.now() });
+    }
+    /** Drop a cached entry (event-driven refresh hook, symmetric to GroupMdCache). */
+    invalidate(groupNo, shortId) {
+        const k = this.key(groupNo, shortId);
+        if (k === null)
+            return;
+        this.mem.delete(k);
+    }
+}
 //# sourceMappingURL=group-md-cache.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"group-md-cache.js","sourceRoot":"","sources":["../src/group-md-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAUH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAElE;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC;AAClF,CAAC;AAOD,MAAM,OAAO,YAAY;IACN,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IACrC,KAAK,CAAS;IACd,GAAG,CAAe;IAEnC;;;;;OAKG;IACH,YAAY,QAAgB,uBAAuB,EAAE,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QACvF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,OAAe;QACjB,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACjE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,4DAA4D;IAC5D,GAAG,CAAC,OAAe,EAAE,KAAmB;QACtC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,OAAO;QACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,OAAO;QACpC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"group-md-cache.js","sourceRoot":"","sources":["../src/group-md-cache.ts"],"names":[],"mappings":"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"}

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

@@ -27,6 +27,11 @@
 /**
  * Provisional `event.type` literals treated as a GROUP.md change. PROVISIONAL —
  * see the calibration note above. Overridable via `config.serverMdEventTypes`.
+ *
+ * Both an UPDATE and a DELETE of the server GROUP.md drive the same action —
+ * INVALIDATE the cached entry so the next turn re-fetches (an updated entry is
+ * re-read; a deleted one 404s and cleanly degrades to the local fallback), so
+ * `group_md_deleted` sits alongside `group_md_updated` here (P3-2 deleted tail).
  */
 export declare const DEFAULT_GROUP_MD_EVENT_TYPES: readonly string[];
 /** The `payload.event` shape (mirrors MessagePayload.event in octo/types.ts). */
@@ -35,9 +40,36 @@ export interface GroupMdEventLike {
     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.
+ * True iff this event signals a GROUP.md change (update or delete) 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;
+/**
+ * Provisional `event.type` literals treated as a THREAD.md change (P3-2). Same
+ * PROVISIONAL status as the group literals above — the exact wire literal is not
+ * yet confirmed from a captured event, so it is named after the design and is
+ * overridable via `config.threadMdEventTypes` without a code change. As on the
+ * group side, both update and delete map to the same invalidate action.
+ */
+export declare const DEFAULT_THREAD_MD_EVENT_TYPES: readonly string[];
+/**
+ * The `payload.event` shape for a THREAD.md change — like {@link GroupMdEventLike}
+ * but also carrying `short_id`, which locates the subarea whose composite-keyed
+ * (`groupNo::shortId`) cache entry to invalidate. `short_id` is already part of
+ * MessagePayload.event (octo/types.ts).
+ */
+export interface ThreadMdEventLike {
+    type?: string;
+    group_no?: string;
+    short_id?: string;
+}
+/**
+ * True iff this event signals a THREAD.md change (update or delete). The literal
+ * sets for group vs thread are DISJOINT (`group_md_*` vs `thread_md_*`), so a
+ * thread event never trips the group invalidation and vice versa — the two
+ * classifiers stay mutually exclusive, matching the read/write mutual-exclusion
+ * contract of #88 P3.
+ */
+export declare function isThreadMdUpdateEvent(event: ThreadMdEventLike | undefined, eventTypes?: readonly string[]): boolean;

package/dist/group-md-events.js

@@ -27,17 +27,48 @@
 /**
  * Provisional `event.type` literals treated as a GROUP.md change. PROVISIONAL —
  * see the calibration note above. Overridable via `config.serverMdEventTypes`.
+ *
+ * Both an UPDATE and a DELETE of the server GROUP.md drive the same action —
+ * INVALIDATE the cached entry so the next turn re-fetches (an updated entry is
+ * re-read; a deleted one 404s and cleanly degrades to the local fallback), so
+ * `group_md_deleted` sits alongside `group_md_updated` here (P3-2 deleted tail).
  */
-export const DEFAULT_GROUP_MD_EVENT_TYPES = ['group_md_updated'];
+export const DEFAULT_GROUP_MD_EVENT_TYPES = [
+    'group_md_updated',
+    'group_md_deleted',
+];
 /**
- * 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.
+ * True iff this event signals a GROUP.md change (update or delete) 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);
 }
+/**
+ * Provisional `event.type` literals treated as a THREAD.md change (P3-2). Same
+ * PROVISIONAL status as the group literals above — the exact wire literal is not
+ * yet confirmed from a captured event, so it is named after the design and is
+ * overridable via `config.threadMdEventTypes` without a code change. As on the
+ * group side, both update and delete map to the same invalidate action.
+ */
+export const DEFAULT_THREAD_MD_EVENT_TYPES = [
+    'thread_md_updated',
+    'thread_md_deleted',
+];
+/**
+ * True iff this event signals a THREAD.md change (update or delete). The literal
+ * sets for group vs thread are DISJOINT (`group_md_*` vs `thread_md_*`), so a
+ * thread event never trips the group invalidation and vice versa — the two
+ * classifiers stay mutually exclusive, matching the read/write mutual-exclusion
+ * contract of #88 P3.
+ */
+export function isThreadMdUpdateEvent(event, eventTypes = DEFAULT_THREAD_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

@@ -1 +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"}
+{"version":3,"file":"group-md-events.js","sourceRoot":"","sources":["../src/group-md-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAsB;IAC7D,kBAAkB;IAClB,kBAAkB;CACnB,CAAC;AAQF;;;;;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;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsB;IAC9D,mBAAmB;IACnB,mBAAmB;CACpB,CAAC;AAcF;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAoC,EACpC,aAAgC,6BAA6B;IAE7D,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,80 @@
+/**
+ * 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, type ThreadMdWriteback } 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";
+/** MCP server name; the tool surfaces as `mcp__thread_md__update_thread_md`. */
+export declare const THREAD_MD_TOOL_SERVER_NAME = "thread_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;
+}
+/** Shared deps the thread write-back tool needs. */
+export interface ThreadMdToolDeps {
+    writeback: ThreadMdWriteback;
+    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;
+/**
+ * Build the THREAD.md tool DEFINITIONS for one agent turn (P3-2). The thread
+ * analogue of {@link buildGroupMdTools}: the tool surfaces as
+ * `mcp__thread_md__update_thread_md` and writes THIS thread's OWN THREAD.md
+ * (PUT /v1/bot/groups/{groupNo}/threads/{shortId}/md), NEVER the parent group's
+ * GROUP.md — the thread/group split is mutually exclusive (#88 P3).
+ * index.ts only ever wires the group tool OR this thread tool for a turn (chosen
+ * by channelId shape), so the two never co-exist in one session.
+ *
+ * `coords.channelId` MUST be a thread composite (`<groupNo>____<shortId>`); the
+ * caller (index.ts) guarantees this by routing on `isThreadChannelId`. The
+ * owner-gate is identical to the group tool (bot-owner-only, independent of the
+ * token's server-side thread permission).
+ */
+export declare function buildThreadMdTools(deps: ThreadMdToolDeps, coords: GroupMdSessionCoords, ownerUid: string): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    content: z.ZodString;
+}>[];
+/**
+ * Build the THREAD.md write-back MCP server for one agent turn. `coords` targets
+ * the thread (its composite channelId) + supplies the caller uid; `ownerUid` is
+ * the owner gate.
+ */
+export declare function createThreadMdToolServer(deps: ThreadMdToolDeps, coords: GroupMdSessionCoords, ownerUid: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/group-md-tool.js

@@ -0,0 +1,181 @@
+/**
+ * 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, extractThreadShortId, isThreadChannelId, } from './octo/channel-id.js';
+import { GroupMdContentTooLargeError, MAX_GROUP_MD_CONTENT_BYTES, ThreadMdContentTooLargeError, MAX_THREAD_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';
+/** MCP server name; the tool surfaces as `mcp__thread_md__update_thread_md`. */
+export const THREAD_MD_TOOL_SERVER_NAME = 'thread_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),
+    });
+}
+/**
+ * Build the THREAD.md tool DEFINITIONS for one agent turn (P3-2). The thread
+ * analogue of {@link buildGroupMdTools}: the tool surfaces as
+ * `mcp__thread_md__update_thread_md` and writes THIS thread's OWN THREAD.md
+ * (PUT /v1/bot/groups/{groupNo}/threads/{shortId}/md), NEVER the parent group's
+ * GROUP.md — the thread/group split is mutually exclusive (#88 P3).
+ * index.ts only ever wires the group tool OR this thread tool for a turn (chosen
+ * by channelId shape), so the two never co-exist in one session.
+ *
+ * `coords.channelId` MUST be a thread composite (`<groupNo>____<shortId>`); the
+ * caller (index.ts) guarantees this by routing on `isThreadChannelId`. The
+ * owner-gate is identical to the group tool (bot-owner-only, independent of the
+ * token's server-side thread permission).
+ */
+export function buildThreadMdTools(deps, coords, ownerUid) {
+    const isOwner = coords.fromUid === ownerUid && ownerUid !== '';
+    return [
+        tool('update_thread_md', 'Persist new THREAD.md content for THIS thread (subarea) on the server (it ' +
+            "becomes the thread'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. This writes the thread\'s OWN THREAD.md, never the parent ' +
+            "group's GROUP.md. Last write wins server-side — compose the complete " +
+            'updated document, do not assume a concurrent edit merged.', {
+            content: z
+                .string()
+                .describe('Full replacement THREAD.md document (≤10240 bytes UTF-8).'),
+        }, async (args) => {
+            try {
+                if (!isOwner) {
+                    return errResult('Only the bot owner can update THREAD.md.');
+                }
+                if (!isThreadChannelId(coords.channelId)) {
+                    return errResult('This channel is not a thread — THREAD.md is only writable from a thread.');
+                }
+                const groupNo = extractParentGroupNo(coords.channelId);
+                const shortId = extractThreadShortId(coords.channelId);
+                if (!groupNo || !shortId) {
+                    return errResult('Could not resolve a thread (groupNo/shortId) from this channel.');
+                }
+                // 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_THREAD_MD_CONTENT_BYTES) {
+                    return errResult(`content is ${bytes} bytes, over the ${MAX_THREAD_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,
+                    shortId,
+                    content: args.content,
+                });
+                return jsonResult({
+                    updated: {
+                        groupNo: res.groupNo,
+                        shortId: res.shortId,
+                        version: res.version,
+                        bytes: res.bytes,
+                    },
+                });
+            }
+            catch (err) {
+                if (err instanceof ThreadMdContentTooLargeError) {
+                    return errResult(`content is ${err.bytes} bytes, over the ${MAX_THREAD_MD_CONTENT_BYTES}-byte UTF-8 limit.`);
+                }
+                return errResult(err instanceof Error ? err.message : String(err));
+            }
+        }),
+    ];
+}
+/**
+ * Build the THREAD.md write-back MCP server for one agent turn. `coords` targets
+ * the thread (its composite channelId) + supplies the caller uid; `ownerUid` is
+ * the owner gate.
+ */
+export function createThreadMdToolServer(deps, coords, ownerUid) {
+    return createSdkMcpServer({
+        name: THREAD_MD_TOOL_SERVER_NAME,
+        version: '1.0.0',
+        tools: buildThreadMdTools(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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"}