clearclaw 0.6.1 → 0.8.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

@@ -0,0 +1,10 @@
+/**
+ * Assemble the system prompt from framework and user instruction files.
+ * Framework content comes first, user content appended after.
+ * `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): Promise<{
+    prompt: string | undefined;
+    skipped: string[];
+}>;

package/dist/prompt.js

@@ -0,0 +1,78 @@
+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;
+/** Read a file, giving up after READ_TIMEOUT_MS. Returns null on timeout or error. */
+async function readFileOrSkip(file) {
+    // 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 {
+        const content = await Promise.race([fsp.readFile(file, "utf-8"), timeout]);
+        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;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Read all .md files from a directory, sorted alphabetically.
+ * Unreadable files are reported by name instead of silently dropped.
+ */
+async function readMarkdownFiles(dir) {
+    if (!fs.existsSync(dir))
+        return { contents: [], skipped: [] };
+    let entries;
+    try {
+        entries = await fsp.readdir(dir);
+    }
+    catch (err) {
+        // 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] };
+    }
+    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.
+ * `prompt` is undefined if no content was found in either directory;
+ * `skipped` names files that existed but could not be read.
+ */
+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.contents.length > 0) {
+        parts.push(framework.contents.join("\n\n---\n\n"));
+    }
+    if (user.contents.length > 0) {
+        parts.push(user.contents.join("\n\n---\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/tool-handlers.d.ts

@@ -13,7 +13,7 @@ export interface ToolPromptResult {
     buttons: Button[][];
     mapResponse: (resp: ButtonResponse) => PermissionResponse;
 }
-export type ToolPromptHandler = (input: Record<string, unknown>, description: string) => ToolPromptResult | null;
+export type ToolPromptHandler = (input: Record<string, unknown>) => ToolPromptResult | null;
 export declare const permissionHandlers: Map<string, ToolPromptHandler>;
 /** Tools that suppress the default rolling status line in routeEngineEvent. */
 export declare const displayHandledTools: Set<string>;

package/dist/tool-handlers.js

@@ -34,8 +34,8 @@ function handleAskUserQuestion(input) {
         },
     };
 }
-function handleExitPlanMode(input, description) {
-    const text = formatExitPlanMode(input, description);
+function handleExitPlanMode(input) {
+    const text = formatExitPlanMode(input);
     return {
         text,
         buttons: [

package/dist/types.d.ts

@@ -4,12 +4,16 @@ 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;
-    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    /** 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): Promise<void>;
+    editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
     deleteMessage(chatId: string, handle: string): Promise<void>;
     pinMessage(chatId: string, handle: string): Promise<void>;
     unpinAllMessages(chatId: string): 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;
@@ -30,11 +43,14 @@ export interface ButtonResponse {
     value: string;
     text?: string;
 }
-export interface SendMessageOpts {
+export type TextFormat = "markdown" | "plain";
+export interface MessageOpts {
     /** When false, skip consuming the typing placeholder (e.g. for tool status messages). */
     consumeTyping?: boolean;
     /** Reply/thread to a specific platform message ID (Telegram reply, Slack thread). */
     replyToMessageId?: string;
+    /** Text format hint. Defaults to "markdown". */
+    format?: TextFormat;
 }
 export interface SendFileOpts {
     caption?: string;
@@ -46,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;
@@ -57,45 +87,98 @@ export interface RunTurnOpts {
     prompt: string;
     attachments?: Attachment[];
     permissionMode: PermissionMode;
-    onPermissionRequest: (req: PermissionRequest) => Promise<PermissionResponse>;
+    onPermissionRequest: (req: ToolCall) => Promise<PermissionResponse>;
     appendSystemPrompt?: string;
     mcpServers?: Record<string, McpServerConfig>;
     signal?: AbortSignal;
+    model?: string;
 }
-export interface PermissionRequest {
+interface ToolCallBase {
     toolName: string;
-    input: Record<string, unknown>;
-    description: string;
-    reason?: string;
     toolUseId: string;
 }
+declare const ACTIONS: {
+    readonly edit: "edit";
+    readonly write: "write";
+    readonly execute: "execute";
+    readonly read: "read";
+    readonly search: "search";
+    readonly fetch: "fetch";
+};
+export type KnownToolCall = (ToolCallBase & {
+    action: typeof ACTIONS.edit;
+    path: string;
+    before: string;
+    after: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.write;
+    path: string;
+    content: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.execute;
+    command: string;
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.read;
+    paths: string[];
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.search;
+    pattern: string;
+    paths?: string[];
+}) | (ToolCallBase & {
+    action: typeof ACTIONS.fetch;
+    url: string;
+});
+export interface UnknownToolCall extends ToolCallBase {
+    action: string;
+    [key: string]: unknown;
+}
+export type ToolCall = KnownToolCall | UnknownToolCall;
+export declare function isKnownToolCall(tool: ToolCall): tool is KnownToolCall;
 export interface PermissionResponse {
     decision: "allow" | "deny";
     message?: string;
     updatedInput?: Record<string, unknown>;
 }
 export interface TurnStats {
-    model: string;
+    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;
+} | {
+    type: "text_chunk";
+    text: string;
 } | {
     type: "tool_use";
-    toolName: string;
-    input: Record<string, unknown>;
-    toolUseId: string;
+    tool: ToolCall;
 } | {
     type: "tool_result";
     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;
@@ -104,12 +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;
@@ -121,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 {
@@ -130,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/dist/types.js

@@ -1,2 +1,13 @@
-export {};
+const ACTIONS = {
+    edit: "edit",
+    write: "write",
+    execute: "execute",
+    read: "read",
+    search: "search",
+    fetch: "fetch",
+};
+const knownActions = new Set(Object.values(ACTIONS));
+export function isKnownToolCall(tool) {
+    return knownActions.has(tool.action);
+}
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearclaw",
-  "version": "0.6.1",
+  "version": "0.8.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",
@@ -26,25 +26,33 @@
   },
   "files": [
     "dist/**/*.js",
-    "dist/**/*.d.ts"
+    "dist/**/*.d.ts",
+    "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": {
@@ -52,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.

package/patches/codex-acp-1.11.0.patch

@@ -0,0 +1,38 @@
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -24471,7 +24471,7 @@
+         return this.createMcpToolProgressEvent(notification.params);
+       case "account/rateLimits/updated":
+         this.handleRateLimitsUpdated(notification.params);
+-        return null;
++        return this.createUsageUpdateFromState();
+       case "account/updated":
+         this.onAccountUpdated?.(notification.params);
+         return null;
+@@ -25155,6 +25155,9 @@
+   }
+   createUsageUpdate(params) {
+     this.handleTokenUsageUpdated(params);
++    return this.createUsageUpdateFromState();
++  }
++  createUsageUpdateFromState() {
+     const used = this.sessionState.lastTokenUsage?.totalTokens;
+     const size = this.sessionState.modelContextWindow;
+     if (used == null || size == null || size <= 0) {
+@@ -25163,7 +25166,15 @@
+     return {
+       sessionUpdate: "usage_update",
+       used,
+-      size
++      size,
++      ...this.sessionState.rateLimits ? {
++        _meta: {
++          "_codex/rateLimits": Array.from(this.sessionState.rateLimits.values(), (entry) => ({
++            ...entry.snapshot,
++            limitId: entry.limitId
++          }))
++        }
++      } : {}
+     };
+   }
+   handleRateLimitsUpdated(params) {