clearclaw 0.7.0 → 0.9.0

package/dist/plan-usage.d.ts

@@ -0,0 +1,6 @@
+import type { EngineEvent, PlanUsageState } from "./types.js";
+/** Latest normalized readings shared by workspaces on the same engine/account. */
+export declare function recordPlanUsage(state: PlanUsageState, event: Extract<EngineEvent, {
+    type: "plan_usage";
+}>): void;
+export declare function formatPlanUsage(state?: PlanUsageState, maxLength?: number): string;

package/dist/plan-usage.js

@@ -0,0 +1,31 @@
+/** Latest normalized readings shared by workspaces on the same engine/account. */
+export function recordPlanUsage(state, event) {
+    for (const window of event.windows)
+        state.windows.set(window.id, window);
+    if (event.isUsingOverage !== undefined)
+        state.isUsingOverage = event.isUsingOverage;
+}
+export function formatPlanUsage(state, maxLength = 4096) {
+    // A window with nothing to report is omitted: "5h ?" tells the reader less than
+    // its absence does, and the seeded windows start out unreported.
+    const parts = [];
+    for (const window of state?.windows.values() ?? []) {
+        if (window.usedPercent !== undefined)
+            parts.push(`${window.label} ${Math.round(window.usedPercent)}%`);
+        else if (window.limited)
+            parts.push(`${window.label} limited`);
+    }
+    if (state?.isUsingOverage)
+        parts.push("overage");
+    const kept = [];
+    for (const part of parts) {
+        const remaining = parts.length - kept.length - 1;
+        const candidate = [...kept, part].join(", ") + (remaining ? ` +${remaining} more` : "");
+        if (candidate.length > maxLength)
+            break;
+        kept.push(part);
+    }
+    const omitted = parts.length - kept.length;
+    return kept.join(", ") + (omitted ? `${kept.length ? " " : ""}+${omitted} more` : "");
+}
+//# sourceMappingURL=plan-usage.js.map

package/dist/prompt.d.ts

@@ -1,6 +1,10 @@
 /**
  * Assemble the system prompt from framework and user instruction files.
  * Framework content comes first, user content appended after.
- * Returns undefined if no content found in either directory.
+ * `prompt` is undefined if no content was found in either directory;
+ * `skipped` names files that existed but could not be read.
  */
-export declare function assemblePrompt(frameworkDir: string, instructionsDir: string): string | undefined;
+export declare function assemblePrompt(frameworkDir: string, instructionsDir: string): Promise<{
+    prompt: string | undefined;
+    skipped: string[];
+}>;

package/dist/prompt.js

@@ -1,35 +1,89 @@
-import fs from "node:fs";
+import fsp from "node:fs/promises";
 import path from "node:path";
+import log from "./logger.js";
+// A cloud-synced instructions dir (OneDrive/iCloud "dataless" placeholder) can
+// block a read indefinitely. Reading it synchronously froze the whole relay.
+const READ_TIMEOUT_MS = 5000;
+/** Settle with `op`, or with null once READ_TIMEOUT_MS passes first. */
+async function withReadTimeout(op) {
+    // ponytail: Promise.race, not AbortSignal — an abort can't interrupt a read
+    // already blocked in libuv's threadpool, which is exactly what a
+    // cloud-placeholder file does.
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), READ_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([op, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Read a file, giving up after READ_TIMEOUT_MS. Returns null on timeout or error. */
+async function readFileOrSkip(file) {
+    try {
+        const content = await withReadTimeout(fsp.readFile(file, "utf-8"));
+        if (content === null) {
+            log.warn("[prompt] timed out reading %s after %dms — skipping", file, READ_TIMEOUT_MS);
+            return null;
+        }
+        return content.trim();
+    }
+    catch (err) {
+        log.warn({ err }, "[prompt] could not read %s — skipping", file);
+        return null;
+    }
+}
 /**
  * Read all .md files from a directory, sorted alphabetically.
- * Returns empty array if directory doesn't exist.
+ * Unreadable files are reported by name instead of silently dropped.
  */
-function readMarkdownFiles(dir) {
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter((f) => f.endsWith(".md"))
-        .sort()
-        .map((f) => fs.readFileSync(path.join(dir, f), "utf-8").trim())
-        .filter(Boolean);
+async function readMarkdownFiles(dir) {
+    let entries;
+    try {
+        // Listing a cloud-synced dir can block just like reading one (seen with
+        // Google Drive under a launchd daemon before macOS granted access).
+        entries = await withReadTimeout(fsp.readdir(dir));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { contents: [], skipped: [] };
+        // Cloud-synced dirs (Google Drive File Provider) can transiently refuse a listing with EPERM.
+        log.warn({ err }, "[prompt] could not list %s — skipping", dir);
+        return { contents: [], skipped: [dir] };
+    }
+    if (entries === null) {
+        log.warn("[prompt] timed out listing %s after %dms — skipping", dir, READ_TIMEOUT_MS);
+        return { contents: [], skipped: [dir] };
+    }
+    const names = entries.filter((f) => f.endsWith(".md")).sort();
+    const results = await Promise.all(names.map(async (f) => ({ name: f, text: await readFileOrSkip(path.join(dir, f)) })));
+    return {
+        contents: results.map((r) => r.text).filter((text) => Boolean(text)),
+        skipped: results.filter((r) => r.text === null).map((r) => r.name),
+    };
 }
 /**
  * Assemble the system prompt from framework and user instruction files.
  * Framework content comes first, user content appended after.
- * Returns undefined if no content found in either directory.
+ * `prompt` is undefined if no content was found in either directory;
+ * `skipped` names files that existed but could not be read.
  */
-export function assemblePrompt(frameworkDir, instructionsDir) {
-    const framework = readMarkdownFiles(frameworkDir);
-    const user = readMarkdownFiles(instructionsDir);
-    if (framework.length === 0 && user.length === 0)
-        return undefined;
+export async function assemblePrompt(frameworkDir, instructionsDir) {
+    const framework = await readMarkdownFiles(frameworkDir);
+    const user = await readMarkdownFiles(instructionsDir);
+    const skipped = [...framework.skipped, ...user.skipped];
+    if (framework.contents.length === 0 && user.contents.length === 0) {
+        return { prompt: undefined, skipped };
+    }
     const parts = [];
-    if (framework.length > 0) {
-        parts.push(framework.join("\n\n---\n\n"));
+    if (framework.contents.length > 0) {
+        parts.push(framework.contents.join("\n\n---\n\n"));
     }
-    if (user.length > 0) {
-        parts.push(user.join("\n\n---\n\n"));
+    if (user.contents.length > 0) {
+        parts.push(user.contents.join("\n\n---\n\n"));
     }
-    return parts.join("\n\n");
+    return { prompt: parts.join("\n\n"), skipped };
 }
 //# sourceMappingURL=prompt.js.map

package/dist/scheduler.d.ts

@@ -0,0 +1,15 @@
+import type { Config, ScheduleEntry } from "./config.js";
+import type { InboundMessage } from "./types.js";
+export declare class Scheduler {
+    private config;
+    private inject;
+    private jobs;
+    constructor(config: Config, inject: (msg: Pick<InboundMessage, "origin" | "text">) => void);
+    start(): void;
+    stop(): void;
+    add(entry: ScheduleEntry): void;
+    remove(id: string): void;
+    toggle(id: string, enabled: boolean): void;
+    list(): ScheduleEntry[];
+    private createJob;
+}

package/dist/scheduler.js

@@ -0,0 +1,82 @@
+import { Cron } from "croner";
+import log from "./logger.js";
+export class Scheduler {
+    config;
+    inject;
+    jobs = new Map();
+    constructor(config, inject) {
+        this.config = config;
+        this.inject = inject;
+    }
+    start() {
+        const schedules = this.config.listSchedules();
+        let started = 0;
+        for (const entry of schedules) {
+            if (entry.enabled) {
+                this.createJob(entry);
+                started++;
+            }
+        }
+        if (started > 0) {
+            log.info("[scheduler] started %d schedule(s)", started);
+        }
+    }
+    stop() {
+        for (const [id, job] of this.jobs) {
+            job.stop();
+            log.info("[scheduler] stopped job %s", id);
+        }
+        this.jobs.clear();
+    }
+    add(entry) {
+        this.config.addSchedule(entry);
+        if (entry.enabled) {
+            this.createJob(entry);
+        }
+        log.info("[scheduler] added %s: %s → %s", entry.id, entry.cron, entry.prompt.slice(0, 60));
+    }
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (job) {
+            job.stop();
+            this.jobs.delete(id);
+        }
+        this.config.removeSchedule(id);
+        log.info("[scheduler] removed %s", id);
+    }
+    toggle(id, enabled) {
+        this.config.updateSchedule(id, { enabled });
+        if (enabled) {
+            const entry = this.config.listSchedules().find((s) => s.id === id);
+            if (entry && !this.jobs.has(id)) {
+                this.createJob(entry);
+            }
+        }
+        else {
+            const job = this.jobs.get(id);
+            if (job) {
+                job.stop();
+                this.jobs.delete(id);
+            }
+        }
+        log.info("[scheduler] %s → %s", id, enabled ? "enabled" : "disabled");
+    }
+    list() {
+        return this.config.listSchedules();
+    }
+    createJob(entry) {
+        const opts = {};
+        if (entry.timezone)
+            opts.timezone = entry.timezone;
+        const job = new Cron(entry.cron, opts, () => {
+            log.info("[scheduler] firing %s: %s", entry.id, entry.prompt.slice(0, 60));
+            this.inject({ origin: { kind: "scheduler", scheduleId: entry.id }, text: entry.prompt });
+            if (!job.nextRun()) {
+                this.remove(entry.id);
+                log.info("[scheduler] one-shot %s auto-deleted", entry.id);
+            }
+        });
+        this.jobs.set(entry.id, job);
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/transcribe.d.ts

@@ -0,0 +1,13 @@
+import type { Attachment } from "./types.js";
+export declare function isAudio(att: Attachment): boolean;
+/** Interim/Text frames replace the current segment; Endpoint finalizes it. */
+export declare function reduceTranscriptFrames(frames: Array<{
+    type: string;
+    data?: string;
+}>): string;
+/** The service's last word on a stream is an Endpoint; anything else means text may still be coming. */
+export declare function isComplete(frames: Array<{
+    type: string;
+}>): boolean;
+/** Speech-to-text via the stream Claude Code's /voice uses, authenticated with the Claude.ai OAuth token. */
+export declare function transcribeAudio(att: Attachment): Promise<string>;

package/dist/transcribe.js

@@ -0,0 +1,157 @@
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const RATE = 16000;
+const FRAME_BYTES = RATE * 2 / 10; // 100 ms of s16le mono
+const STREAM_URL = "wss://api.anthropic.com/api/ws/speech_to_text/voice_stream?" + new URLSearchParams({
+    encoding: "linear16", sample_rate: String(RATE), channels: "1", endpointing_ms: "300", utterance_end_ms: "1000",
+    language: "en", use_conversation_engine: "true", stt_provider: "deepgram-nova3",
+});
+export function isAudio(att) {
+    return att.mimeType.startsWith("audio/");
+}
+/** Interim/Text frames replace the current segment; Endpoint finalizes it. */
+export function reduceTranscriptFrames(frames) {
+    const finals = [];
+    let current = "";
+    for (const f of frames) {
+        if (f.type === "TranscriptInterim" || f.type === "TranscriptText")
+            current = f.data ?? "";
+        else if (f.type === "TranscriptEndpoint") {
+            if (current)
+                finals.push(current);
+            current = "";
+        }
+    }
+    return [...finals, current].filter(Boolean).join(" ").trim();
+}
+/** The service's last word on a stream is an Endpoint; anything else means text may still be coming. */
+export function isComplete(frames) {
+    return frames.at(-1)?.type === "TranscriptEndpoint";
+}
+/** Speech-to-text via the stream Claude Code's /voice uses, authenticated with the Claude.ai OAuth token. */
+export async function transcribeAudio(att) {
+    const token = readClaudeToken();
+    if (!token)
+        throw new Error("no Claude.ai credentials");
+    const pcm = await decodeToPcm16k(att.buffer);
+    const text = await voiceStream(pcm, token);
+    if (!text)
+        throw new Error("empty transcript");
+    return text;
+}
+function readClaudeToken() {
+    try {
+        const raw = process.platform === "darwin"
+            ? execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+            : fs.readFileSync(path.join(os.homedir(), ".claude", ".credentials.json"), "utf8");
+        const oauth = JSON.parse(raw).claudeAiOauth;
+        if (!oauth?.accessToken || !(oauth.expiresAt > Date.now()))
+            return null;
+        return oauth.accessToken;
+    }
+    catch {
+        return null;
+    }
+}
+// The service requires an explicit PCM encoding; it does not accept OGG/Opus.
+function decodeToPcm16k(input) {
+    return new Promise((resolve, reject) => {
+        const ff = spawn("ffmpeg", ["-loglevel", "error", "-i", "pipe:0", "-f", "s16le", "-ac", "1", "-ar", String(RATE), "pipe:1"], { timeout: 30_000 });
+        const out = [];
+        let stderr = "";
+        ff.stdout.on("data", (c) => out.push(c));
+        ff.stderr.on("data", (c) => (stderr += c));
+        ff.on("error", (e) => reject(new Error(`ffmpeg failed: ${e.message}`)));
+        ff.on("close", (code) => {
+            const pcm = Buffer.concat(out);
+            if (code === 0 && pcm.length > 0)
+                resolve(pcm);
+            else
+                reject(new Error(`ffmpeg failed: ${stderr.trim().split("\n").pop() || `exit ${code}`}`));
+        });
+        ff.stdin.on("error", () => { }); // ffmpeg can exit before reading all input; "close" reports why
+        ff.stdin.end(input);
+    });
+}
+function voiceStream(pcm, token) {
+    // The service trims ~0.5 s at each end; pad with silence so the first and last words survive.
+    const pad = Buffer.alloc(RATE); // 0.5 s
+    const audio = Buffer.concat([pad, pcm, pad]);
+    const durationMs = (pcm.length / 2 / RATE) * 1000;
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(STREAM_URL, { headers: {
+                Authorization: `Bearer ${token}`, "User-Agent": "claude-cli/2.1.284 (external, cli)",
+                "x-app": "cli", "anthropic-client-platform": "claude_code_cli",
+            } }); // Node (undici) accepts { headers }; the DOM typings do not
+        ws.binaryType = "arraybuffer";
+        const frames = [];
+        let closing = false;
+        let done = false;
+        let keepalive;
+        let idle;
+        let safety;
+        const finish = (err) => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(keepalive);
+            clearTimeout(idle);
+            clearTimeout(safety);
+            try {
+                ws.close();
+            }
+            catch { /* already closed */ }
+            if (err)
+                reject(err);
+            else
+                resolve(reduceTranscriptFrames(frames));
+        };
+        // Finish on idle rather than on the first Endpoint after CloseStream: with unpaced
+        // sending, that endpoint can arrive before the tail of the audio is transcribed.
+        // A partial transcript is never a success: an incomplete stream waits for the safety timeout.
+        const bump = () => {
+            if (!closing)
+                return;
+            clearTimeout(idle);
+            idle = setTimeout(() => { if (isComplete(frames))
+                finish(); }, 1500);
+        };
+        safety = setTimeout(() => finish(new Error("timed out")), 15_000 + durationMs);
+        ws.onopen = () => {
+            const keepAlive = () => ws.send(JSON.stringify({ type: "KeepAlive" }));
+            keepAlive();
+            keepalive = setInterval(keepAlive, 8000);
+            for (let off = 0; off < audio.length; off += FRAME_BYTES)
+                ws.send(audio.subarray(off, off + FRAME_BYTES));
+            closing = true;
+            ws.send(JSON.stringify({ type: "CloseStream" }));
+            bump();
+        };
+        ws.onmessage = (ev) => {
+            let msg;
+            try {
+                msg = JSON.parse(typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString());
+            }
+            catch {
+                return;
+            }
+            bump();
+            if (msg.type === "TranscriptError" || msg.type === "error") {
+                finish(new Error(`voice stream error: ${JSON.stringify(msg.data ?? msg).slice(0, 200)}`));
+            }
+            else if (msg.type) {
+                frames.push({ type: msg.type, data: typeof msg.data === "string" ? msg.data : undefined });
+            }
+        };
+        ws.onerror = () => finish(new Error("voice stream error: connection failed"));
+        ws.onclose = (ev) => {
+            if (closing && isComplete(frames))
+                finish();
+            else
+                finish(new Error(`voice stream error: closed ${ev.code} ${ev.reason}`.trim()));
+        };
+    });
+}
+//# sourceMappingURL=transcribe.js.map

package/dist/types.d.ts

@@ -4,9 +4,13 @@ export interface ChannelEvents {
 }
 export interface Channel {
     name: string;
+    /** Character budget for the chat status surface, e.g. Slack channel topic. */
+    statusMaxLength?: number;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
+    /** This user's own top-level DM with the bot — home's only valid chat. */
+    isRootDM(chatId: string, userId: string): boolean;
     sendMessage(chatId: string, text: string, opts?: MessageOpts): Promise<string[]>;
     sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
     editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
@@ -17,6 +21,15 @@ export interface Channel {
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
     sendFile(chatId: string, buffer: Buffer, filename: string, opts?: SendFileOpts): Promise<void>;
     reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;
+    /**
+     * Group an existing chat under its Project, creating the grouping if it does not exist yet.
+     * Returns a note when grouping did not happen, so the caller can tell the user.
+     */
+    groupProjectChat?(projectName: string, chatId: string): Promise<string | undefined>;
+    /** Create a peer chat. Returns an opaque chat ID; grouping is a separate step. */
+    createProjectChat?(projectName: string, anchor: string, title: string): Promise<string>;
+    /** Close a workspace's chat and remove its Project grouping, regardless of origin. */
+    closeProjectChat?(chatId: string, projectName?: string): Promise<void>;
     on<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
     off<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
     emit<K extends keyof ChannelEvents>(event: K, ...args: ChannelEvents[K]): boolean;
@@ -49,10 +62,24 @@ export interface SessionInfo {
     lastModified: number;
     gitBranch?: string;
 }
+/** Chronological conversation text, excluding tool payloads and internal reasoning. */
+export interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface SessionHistoryOpts {
+    sessionId: string;
+    cwd: string;
+    signal?: AbortSignal;
+}
 export interface Engine {
     name: string;
+    /** Known account windows to show as unknown before the first observation. */
+    planUsageWindows?: readonly PlanUsageWindow[];
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
     listSessions(cwd: string): Promise<SessionInfo[]>;
+    /** Read history without submitting a new prompt. Reject on unsupported/failed retrieval. */
+    getSessionMessages(opts: SessionHistoryOpts): Promise<SessionMessage[]>;
 }
 export interface RunTurnOpts {
     sessionId: string | null;
@@ -64,6 +91,7 @@ export interface RunTurnOpts {
     appendSystemPrompt?: string;
     mcpServers?: Record<string, McpServerConfig>;
     signal?: AbortSignal;
+    model?: string;
 }
 interface ToolCallBase {
     toolName: string;
@@ -112,11 +140,24 @@ export interface PermissionResponse {
     updatedInput?: Record<string, unknown>;
 }
 export interface TurnStats {
+    modelLabel?: string;
     model: string | null;
     contextUsed: number;
     contextWindow: number;
     toolCalls: Record<string, number>;
 }
+/** Account quota, distinct from a session's context/token usage. Reset times are Unix seconds. */
+export interface PlanUsageWindow {
+    id: string;
+    label: string;
+    usedPercent?: number;
+    resetsAt?: number;
+    limited?: boolean;
+}
+export interface PlanUsageState {
+    windows: Map<string, PlanUsageWindow>;
+    isUsingOverage?: boolean;
+}
 export type EngineEvent = {
     type: "text";
     text: string;
@@ -131,9 +172,13 @@ export type EngineEvent = {
     toolName: string;
     output: string;
 } | {
-    type: "rate_limit";
-    status: string;
-    resetsAt?: number;
+    type: "plan_usage";
+    windows: PlanUsageWindow[];
+    isUsingOverage?: boolean;
+} | {
+    type: "session";
+    sessionId: string;
+    model?: string;
 } | {
     type: "done";
     sessionId: string;
@@ -142,13 +187,27 @@ export type EngineEvent = {
     type: "error";
     message: string;
 };
+export interface EngineHandoff {
+    engine: string;
+    sessionId: string;
+    cwd: string;
+}
 export interface Workspace {
     name: string;
     cwd: string;
-    chat_id: string;
+    chat_id: string | null;
     current_session_id: string | null;
+    engine_handoff?: EngineHandoff;
     behavior?: "assistant" | "relay";
     engine?: string;
+    model?: string;
+    project?: string;
+    description?: string;
+    spawnedFrom?: string;
+    pending_brief?: {
+        fromWorkspace: string;
+        text: string;
+    };
 }
 export interface UserInfo {
     id: string;
@@ -160,6 +219,8 @@ export interface Attachment {
     buffer: Buffer;
     mimeType: string;
     filename?: string;
+    /** Absolute path where the orchestrator saved this file to disk. */
+    savedAs?: string;
 }
 /** Context from a replied-to / quoted message. */
 export interface ReplyContext {
@@ -169,10 +230,21 @@ export interface ReplyContext {
     mediaType?: string;
 }
 export type ChatType = "dm" | "group";
+/** Where an inbound message came from. */
+export type MessageOrigin = {
+    kind: "user";
+    user: UserInfo;
+} | {
+    kind: "scheduler";
+    scheduleId: string;
+} | {
+    kind: "peer";
+    workspaceName: string;
+};
 export interface InboundMessage {
     chatId: string;
     chatType: ChatType;
-    user: UserInfo;
+    origin: MessageOrigin;
     text: string;
     messageId?: string;
     replyTo?: ReplyContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearclaw",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.",
   "type": "module",
   "license": "MIT",
@@ -27,26 +27,32 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "prompts/**/*.md"
+    "prompts/**/*.md",
+    "scripts/patch-codex-acp.mjs",
+    "patches/**"
   ],
   "scripts": {
     "start": "tsx src/index.ts daemon",
     "dev": "tsx --watch src/index.ts daemon",
     "dev:relay": "nodemon --watch dist --exec 'node dist/index.js daemon'",
     "build": "tsc",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "postinstall": "node scripts/patch-codex-acp.mjs"
   },
   "dependencies": {
+    "@agentclientprotocol/codex-acp": "1.11.0",
     "@agentclientprotocol/sdk": "^0.16.1",
     "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@slack/bolt": "^4.6.0",
+    "croner": "^10.0.1",
     "diff": "^8.0.3",
     "grammy": "^1.30.0",
     "mime": "^4.1.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "pino-roll": "^4.0.0",
-    "slackify-markdown": "^5.0.0",
     "telegramify-markdown": "^1.3.3"
   },
   "devDependencies": {
@@ -54,6 +60,7 @@
     "@types/diff": "^7.0.2",
     "@types/node": "^22.0.0",
     "nodemon": "^3.1.14",
+    "telegram": "^2.26.22",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }

package/patches/README.md

@@ -0,0 +1,13 @@
+# Codex ACP usage metadata backport
+
+ClearClaw temporarily pins `@agentclientprotocol/codex-acp` to npm version `1.11.0` and backports the usage notification changes from [codex-acp PR #334](https://github.com/agentclientprotocol/codex-acp/pull/334), head [`b670a4e4914fbd5ffe2d008091e64921dc2684d4`](https://github.com/agentclientprotocol/codex-acp/commit/b670a4e4914fbd5ffe2d008091e64921dc2684d4). The upstream adapter and these adapted changes are Apache-2.0 licensed.
+
+The npm release distributes a bundled `dist/index.js`, so the patch targets that bundle. It forwards account limit updates as ACP `usage_update` notifications and includes all cached quota buckets in `_meta["_codex/rateLimits"]` on context usage updates. Notifications retain the upstream requirement that context usage and a positive context window are known. This does not fetch quotas on demand.
+
+Only the emission changes are backported. Version 1.11.0's existing `mergeRateLimitSnapshot` logic remains intact, including preservation of account-level fields on sparse updates.
+
+`scripts/patch-codex-acp.mjs` runs after installation and uses ClearClaw's existing `diff` dependency. It resolves the installed adapter, checks its exact version and original SHA-256 hash, applies this patch, and verifies the resulting hash. An already patched bundle is accepted, making repeat installation idempotent. Unexpected source fails installation instead of silently dropping quota data.
+
+The installer modifies the resolved dependency in place. In an installation where npm hoists and shares that exact adapter version, other consumers also receive these additive usage metadata notifications. Both the script and patch are included in ClearClaw's published package. Installations using `--ignore-scripts` must explicitly run `node scripts/patch-codex-acp.mjs` from the ClearClaw package directory before relying on Codex quota reporting.
+
+Remove the installer and patch when an upstream release includes this metadata contract, then update the pinned dependency and verify usage notifications.