@mininglamp-oss/cc-channel-octo 1.0.3-dev.3135d38 → 1.0.3-dev.3332be0

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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"}

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

@@ -0,0 +1,183 @@
+/**
+ * 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, updateThreadMd } from './octo/api.js';
+import type { GroupMdCache, ThreadMdCache } 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;
+/**
+ * Hard UTF-8 byte ceiling for THREAD.md content. The thread md endpoint shares
+ * the group md limit (P3-2 contract check: the official Octo web client edits
+ * both group and thread md through the SAME editor, whose `MAX_BYTES` is 10240),
+ * so this is an alias of {@link MAX_GROUP_MD_CONTENT_BYTES} rather than a second
+ * magic number — if the server limit ever diverges, the two can split here.
+ */
+export declare const MAX_THREAD_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>;
+}
+/** The `updateThreadMd` client signature, injectable for testing. */
+export type UpdateThreadMdFn = typeof updateThreadMd;
+/** Thrown when THREAD.md content exceeds {@link MAX_THREAD_MD_CONTENT_BYTES}. */
+export declare class ThreadMdContentTooLargeError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+/** Outcome of a successful THREAD.md write-back. */
+export interface ThreadMdWriteResult {
+    groupNo: string;
+    shortId: string;
+    /** Server-assigned version after the PUT. */
+    version: number;
+    /** UTF-8 byte length of the content that was written. */
+    bytes: number;
+}
+export interface ThreadMdWriteParams {
+    apiUrl: string;
+    botToken: string;
+    groupNo: string;
+    shortId: string;
+    content: string;
+    signal?: AbortSignal;
+}
+/**
+ * Thread analogue of {@link GroupMdWriteback} (P3-2): persists an agent-authored
+ * THREAD.md back to the server (PUT /v1/bot/groups/{groupNo}/threads/{shortId}/md
+ * via `updateThreadMd`), then refreshes the in-memory {@link ThreadMdCache} so
+ * the next resolve does not TTL-refetch a stale copy.
+ *
+ * Carries over every P2-C safety property, adapted to the thread key:
+ *
+ *   1. Same HARD ≤10240-byte (UTF-8) limit ({@link MAX_THREAD_MD_CONTENT_BYTES},
+ *      confirmed to equal the group limit — see that constant). Rejected locally
+ *      BEFORE the PUT so an oversized body never reaches the server.
+ *
+ *   2. The thread PUT, like the group PUT, does NOT compare-and-swap (body is
+ *      just `{ content }`, reply is `{ version }`). All write-backs for the same
+ *      thread are serialized through a per-`groupNo::shortId` promise-chain lock
+ *      so this gateway never races itself. Cross-source last-write-wins remains
+ *      possible by design, identical to the group caveat.
+ *
+ * Keyed by the COMPOSITE `groupNo::shortId` — the SAME key the thread cache and
+ * the P3-1 read side use — so a thread's write lock and cache refresh can never
+ * be confused with its parent group's (which the group coordinator locks by the
+ * bare groupNo). `::` is outside the safe-id charset, so the two key spaces are
+ * disjoint. Owner-gating lives in the MCP tool layer (group-md-tool.ts), not
+ * here. Never persists to disk — the cache it updates is the same memory-only
+ * cache the resolver reads.
+ */
+export declare class ThreadMdWriteback {
+    private readonly cache;
+    /** Injectable PUT client (defaults to the real octo client). */
+    private readonly updateFn;
+    /** Tail of the in-flight write chain per composite key (serializes same-thread writes). */
+    private readonly tails;
+    constructor(cache: ThreadMdCache, 
+    /** Injectable PUT client (defaults to the real octo client). */
+    updateFn?: UpdateThreadMdFn);
+    /** Composite lock key; mirrors ThreadMdCache's `groupNo::shortId`. */
+    private lockKey;
+    /**
+     * 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. Identical policy to
+     * {@link GroupMdWriteback}.
+     */
+    private withLock;
+    /**
+     * Persist `content` as the thread's THREAD.md and refresh the thread cache.
+     *
+     * Rejects with {@link ThreadMdContentTooLargeError} (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: ThreadMdWriteParams): Promise<ThreadMdWriteResult>;
+}