clearclaw 0.7.0 → 0.9.0

package/dist/channel/telegram.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { Bot, InlineKeyboard, InputFile } from "grammy";
+import { Bot, GrammyError, InlineKeyboard, InputFile } from "grammy";
 import mime from "mime";
 import telegramifyMarkdown from "telegramify-markdown";
 import log from "../logger.js";
@@ -15,6 +15,9 @@ export class TelegramChannel extends EventEmitter {
     pendingCallbacks = new Map();
     // Pending text input: chatId → resolve function (for requestText follow-ups)
     pendingTextResolvers = new Map();
+    // Our bot's @username, captured at connect. Used to strip the `@bot` suffix
+    // Telegram appends to commands in group chats.
+    botUsername;
     constructor(botToken, isAuthorized, onUnauthorizedDM) {
         super();
         this.botToken = botToken;
@@ -22,6 +25,31 @@ export class TelegramChannel extends EventEmitter {
         this.onUnauthorizedDM = onUnauthorizedDM;
         this.bot = new Bot(botToken);
     }
+    /**
+     * Strip the `@<botUsername>` suffix Telegram appends to commands in group
+     * chats (`/context@mybot args` → `/context args`), so downstream command
+     * handling — ClearClaw's own `/new` etc. and slash-command pass-through —
+     * sees the bare `/command`. No-op for non-command text and in DMs (no suffix).
+     * Telegram usernames are `[A-Za-z0-9_]`, so they need no regex escaping.
+     */
+    stripCommandMention(text) {
+        if (!this.botUsername || !text.startsWith("/"))
+            return text;
+        return text.replace(new RegExp(`^(/[^\\s@]+)@${this.botUsername}(?=\\s|$)`, "i"), "$1");
+    }
+    async telegramCall(call, label) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            const retryAfter = telegramRetryAfterSeconds(err);
+            if (retryAfter === null)
+                throw err;
+            log.warn("[channel] Telegram rate limited during %s, retrying after %ss", label, retryAfter);
+            await sleep((retryAfter + 1) * 1000);
+            return await call();
+        }
+    }
     async connect() {
         this.bot.on("message:text", (ctx) => {
             const sender = this.extractSender(ctx);
@@ -36,7 +64,7 @@ export class TelegramChannel extends EventEmitter {
             }
             this.emit("message", {
                 ...sender,
-                text: ctx.message.text,
+                text: this.stripCommandMention(ctx.message.text),
                 messageId: String(ctx.message.message_id),
                 replyTo: this.extractReplyContext(ctx.message),
             });
@@ -54,10 +82,17 @@ export class TelegramChannel extends EventEmitter {
             const doc = ctx.message.document;
             await this.handleFileMessage(ctx, doc.file_id, doc.mime_type ?? "application/octet-stream", doc.file_name, ctx.message.caption);
         });
+        // Voice notes and audio files: the orchestrator transcribes them
+        this.bot.on("message:voice", async (ctx) => {
+            const voice = ctx.message.voice;
+            await this.handleFileMessage(ctx, voice.file_id, voice.mime_type ?? "audio/ogg", "voice.ogg", ctx.message.caption);
+        });
+        this.bot.on("message:audio", async (ctx) => {
+            const audio = ctx.message.audio;
+            await this.handleFileMessage(ctx, audio.file_id, audio.mime_type ?? "audio/mpeg", audio.file_name, ctx.message.caption);
+        });
         // Placeholder handlers for unsupported media types
         for (const [filter, label] of [
-            ["message:voice", "Voice message"],
-            ["message:audio", "Audio message"],
             ["message:video", "Video"],
             ["message:sticker", "Sticker"],
         ]) {
@@ -89,6 +124,7 @@ export class TelegramChannel extends EventEmitter {
         await new Promise((resolve) => {
             this.bot.start({
                 onStart: (botInfo) => {
+                    this.botUsername = botInfo.username;
                     log.info(`[channel] Telegram bot: @${botInfo.username}`);
                     resolve();
                 },
@@ -106,6 +142,10 @@ export class TelegramChannel extends EventEmitter {
     ownsId(chatId) {
         return chatId.startsWith("tg:");
     }
+    /** A private chat is the user's own id; a ":thread" suffix means a topic inside it. */
+    isRootDM(chatId, userId) {
+        return /^tg:[1-9]\d*$/.test(chatId) && chatId === userId;
+    }
     async sendMessage(chatId, text, opts) {
         const numId = this.numericId(chatId);
         const chunks = splitMessage(text);
@@ -117,21 +157,22 @@ export class TelegramChannel extends EventEmitter {
                 ? { reply_parameters: { message_id: Number(opts.replyToMessageId) } }
                 : {};
             if (plain) {
-                const sent = await this.bot.api.sendMessage(numId, chunk, replyParams);
+                const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, chunk, { ...this.threadOpts(chatId), ...replyParams }), "sendMessage");
                 handles.push(String(sent.message_id));
             }
             else {
                 const rendered = telegramifyMarkdown(chunk, "escape");
                 try {
-                    const sent = await this.bot.api.sendMessage(numId, rendered, {
+                    const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, rendered, {
+                        ...this.threadOpts(chatId),
                         parse_mode: "MarkdownV2",
                         ...replyParams,
-                    });
+                    }), "sendMessage");
                     handles.push(String(sent.message_id));
                 }
                 catch (err) {
                     log.warn("[channel] sendMessage failed with MarkdownV2, retrying as plain text");
-                    const sent = await this.bot.api.sendMessage(numId, chunk, replyParams);
+                    const sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, chunk, { ...this.threadOpts(chatId), ...replyParams }), "sendMessage");
                     handles.push(String(sent.message_id));
                 }
             }
@@ -164,16 +205,18 @@ export class TelegramChannel extends EventEmitter {
         const mdv2Text = telegramifyMarkdown(text, "escape");
         let sent;
         try {
-            sent = await this.bot.api.sendMessage(numId, mdv2Text, {
+            sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, mdv2Text, {
+                ...this.threadOpts(chatId),
                 reply_markup: keyboard,
                 parse_mode: "MarkdownV2",
-            });
+            }), "sendInteractive");
         }
         catch {
             log.warn("[channel] sendInteractive failed with MarkdownV2, retrying as plain text");
-            sent = await this.bot.api.sendMessage(numId, text, {
+            sent = await this.telegramCall(() => this.bot.api.sendMessage(numId, text, {
+                ...this.threadOpts(chatId),
                 reply_markup: keyboard,
-            });
+            }), "sendInteractive");
         }
         const cleanupAll = () => {
             for (const { cbData } of cbEntries) {
@@ -201,17 +244,18 @@ export class TelegramChannel extends EventEmitter {
             feedbackKeyboard.row();
         }
         try {
-            await this.bot.api.editMessageReplyMarkup(numId, sent.message_id, {
+            await this.telegramCall(() => this.bot.api.editMessageReplyMarkup(numId, sent.message_id, {
                 reply_markup: feedbackKeyboard,
-            });
+            }), "editMessageReplyMarkup");
         }
         catch { /* best-effort */ }
         // If the button requests text, prompt for follow-up input
         if (pressed.requestText) {
-            await this.bot.api.sendMessage(numId, "Add your feedback:", {
+            await this.telegramCall(() => this.bot.api.sendMessage(numId, "Add your feedback:", {
+                ...this.threadOpts(chatId),
                 reply_markup: { force_reply: true },
                 reply_parameters: { message_id: sent.message_id },
-            });
+            }), "sendInteractiveFollowUp");
             const followUpText = await new Promise((resolve) => {
                 this.pendingTextResolvers.set(chatId, resolve);
             });
@@ -222,15 +266,15 @@ export class TelegramChannel extends EventEmitter {
     async editMessage(chatId, handle, text, opts) {
         const numId = this.numericId(chatId);
         if (opts?.format === "plain") {
-            await this.bot.api.editMessageText(numId, Number(handle), text);
+            await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), text), "editMessage");
         }
         else {
             const rendered = telegramifyMarkdown(text, "escape");
             try {
-                await this.bot.api.editMessageText(numId, Number(handle), rendered, { parse_mode: "MarkdownV2" });
+                await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), rendered, { parse_mode: "MarkdownV2" }), "editMessage");
             }
             catch {
-                await this.bot.api.editMessageText(numId, Number(handle), text);
+                await this.telegramCall(() => this.bot.api.editMessageText(numId, Number(handle), text), "editMessage");
             }
         }
     }
@@ -240,13 +284,18 @@ export class TelegramChannel extends EventEmitter {
     }
     async pinMessage(chatId, handle) {
         const numId = this.numericId(chatId);
-        await this.bot.api.pinChatMessage(numId, Number(handle), {
+        await this.telegramCall(() => this.bot.api.pinChatMessage(numId, Number(handle), {
             disable_notification: true,
-        });
+        }), "pinMessage");
     }
+    /** Unpin everything in this chat's scope: the forum topic for a topic chat, else the whole chat. */
     async unpinAllMessages(chatId) {
         const numId = this.numericId(chatId);
-        await this.bot.api.unpinAllChatMessages(numId);
+        const { message_thread_id } = this.threadOpts(chatId);
+        if (message_thread_id)
+            await this.bot.api.unpinAllForumTopicMessages(numId, message_thread_id);
+        else
+            await this.bot.api.unpinAllChatMessages(numId);
     }
     async updateStatus(chatId, text) {
         const existing = this.statusHandles.get(chatId);
@@ -266,7 +315,9 @@ export class TelegramChannel extends EventEmitter {
                 }
             }
         }
-        // No existing handle, or edit failed — create new pinned message
+        // No existing handle, or edit failed — (re)create the pinned status. The handle lives only in
+        // memory, so after a restart the previous status is unknown; clear every pin in scope instead
+        // (topic-scoped for forum topics, so peers in other topics keep theirs).
         try {
             await this.unpinAllMessages(chatId);
         }
@@ -288,10 +339,10 @@ export class TelegramChannel extends EventEmitter {
             const numId = this.numericId(chatId);
             // Send immediately, then repeat every 4s
             await this.bot.api
-                .sendChatAction(numId, "typing")
+                .sendChatAction(numId, "typing", this.threadOpts(chatId))
                 .catch(() => { });
             const interval = setInterval(() => {
-                this.bot.api.sendChatAction(numId, "typing").catch(() => { });
+                this.bot.api.sendChatAction(numId, "typing", this.threadOpts(chatId)).catch(() => { });
             }, 4000);
             this.typingIntervals.set(chatId, interval);
         }
@@ -323,10 +374,13 @@ export class TelegramChannel extends EventEmitter {
             }
             return null;
         }
+        const topicSuffix = ctx.message?.is_topic_message && ctx.message.message_thread_id
+            ? `:${ctx.message.message_thread_id}`
+            : "";
         return {
-            chatId: `tg:${ctx.chat.id}`,
+            chatId: `tg:${ctx.chat.id}${topicSuffix}`,
             chatType: ctx.chat.type === "private" ? "dm" : "group",
-            user,
+            origin: { kind: "user", user },
         };
     }
     /** Extract reply context from a Telegram message, if it's a reply. */
@@ -352,7 +406,7 @@ export class TelegramChannel extends EventEmitter {
             mediaType,
         };
     }
-    /** Shared handler for photo/document messages: download, emit attachment or fallback. */
+    /** Shared handler for file messages: download, emit attachment or fallback. */
     async handleFileMessage(ctx, fileId, mimeType, filename, caption) {
         const sender = this.extractSender(ctx);
         if (!sender)
@@ -387,16 +441,16 @@ export class TelegramChannel extends EventEmitter {
         const file = new InputFile(buffer, filename);
         const caption = opts?.caption;
         if (mimeType.startsWith("image/")) {
-            await this.bot.api.sendPhoto(id, file, { caption });
+            await this.bot.api.sendPhoto(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else if (mimeType.startsWith("video/")) {
-            await this.bot.api.sendVideo(id, file, { caption });
+            await this.bot.api.sendVideo(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else if (mimeType.startsWith("audio/")) {
-            await this.bot.api.sendAudio(id, file, { caption });
+            await this.bot.api.sendAudio(id, file, { caption, ...this.threadOpts(chatId) });
         }
         else {
-            await this.bot.api.sendDocument(id, file, { caption });
+            await this.bot.api.sendDocument(id, file, { caption, ...this.threadOpts(chatId) });
         }
     }
     async reactToMessage(chatId, messageId, emoji) {
@@ -411,6 +465,45 @@ export class TelegramChannel extends EventEmitter {
             log.warn("[channel] failed to set reaction on %s: %s", messageId, err instanceof Error ? err.message : String(err));
         }
     }
+    async createProjectChat(projectName, anchor, title) {
+        await this.validateProjectChat(projectName, anchor);
+        const topic = await this.bot.api.createForumTopic(this.numericId(anchor), title);
+        return `tg:${this.numericId(anchor)}:${topic.message_thread_id}`;
+    }
+    async closeProjectChat(chatId) {
+        const thread = chatId.split(":")[2];
+        if (!thread)
+            throw new Error("Telegram cannot close a whole chat; only topics can be archived");
+        const parentId = this.numericId(chatId);
+        if (parentId > 0) {
+            await this.bot.api.deleteForumTopic(parentId, Number(thread));
+            return;
+        }
+        try {
+            await this.bot.api.closeForumTopic(parentId, Number(thread));
+        }
+        catch (err) {
+            if (err instanceof GrammyError && err.description === "Bad Request: TOPIC_NOT_MODIFIED")
+                return;
+            throw err;
+        }
+    }
+    async validateProjectChat(projectName, anchor) {
+        const parentId = this.numericId(anchor);
+        if (!Number.isFinite(parentId)) {
+            throw new Error(`Telegram project "${projectName}" must use a valid chat ID`);
+        }
+        const chat = await this.bot.api.getChat(parentId);
+        if (chat.type === "private") {
+            const botInfo = await this.bot.api.getMe();
+            if (botInfo.has_topics_enabled)
+                return;
+            throw new Error(`Telegram project "${projectName}" requires Threaded Mode for this bot. Enable it in BotFather, then retry.`);
+        }
+        if (chat.type === "supergroup" && chat.is_forum)
+            return;
+        throw new Error(`Telegram project "${projectName}" requires a forum supergroup. Enable Topics manually in Telegram, then retry.`);
+    }
     /** Download a Telegram file by file_id, returning the raw buffer. */
     async downloadFile(fileId) {
         const file = await this.bot.api.getFile(fileId);
@@ -422,8 +515,14 @@ export class TelegramChannel extends EventEmitter {
             throw new Error(`File download failed: ${resp.status}`);
         return Buffer.from(await resp.arrayBuffer());
     }
+    /** "tg:123" → 123; "tg:123:45" (forum topic) → 123 */
     numericId(chatId) {
-        return Number(chatId.replace(/^tg:/, ""));
+        return Number(chatId.split(":")[1]);
+    }
+    /** Topic part of a composite chat id, as spreadable send options. */
+    threadOpts(chatId) {
+        const thread = chatId.split(":")[2];
+        return thread ? { message_thread_id: Number(thread) } : {};
     }
 }
 const MAX_MSG_LEN = 4096;
@@ -450,4 +549,18 @@ function splitMessage(text) {
         chunks.push(remaining);
     return chunks;
 }
+function telegramRetryAfterSeconds(err) {
+    const candidate = err;
+    const retryAfter = candidate?.parameters?.retry_after;
+    if (typeof retryAfter === "number" && Number.isFinite(retryAfter))
+        return retryAfter;
+    const message = err instanceof Error ? err.message : String(err);
+    const match = message.match(/retry after (\d+)/i);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //# sourceMappingURL=telegram.js.map

package/dist/config.d.ts

@@ -24,7 +24,21 @@ export interface PendingPairing {
 export interface EngineEntry {
     name: string;
     default?: boolean;
-    path: string;
+    path?: string;
+    configPath?: string;
+}
+export interface ScheduleEntry {
+    id: string;
+    cron: string;
+    prompt: string;
+    enabled: boolean;
+    timezone?: string;
+    createdAt: number;
+}
+export interface Project {
+    name: string;
+    description: string;
+    main_workspace: string;
 }
 export declare function resolveDataDir(): string;
 /**
@@ -61,16 +75,38 @@ export declare class Config {
     hasUser(userId: string): boolean;
     addUser(user: AuthorizedUser): void;
     listUsers(): AuthorizedUser[];
+    /** All authorized IDs, including environment-configured and pairing-approved users. */
+    listAuthorizedUserIds(): string[];
     /** env var IDs (in-memory) + pairing-approved users (hot-reload from disk) */
     isAuthorized(userId: string): boolean;
     createPairing(userId: string, userName: string, chatId: string): string;
     consumePairing(code: string): PendingPairing | null;
     private generateCode;
+    /** Home exists before a chat is paired. Never replace an existing home's settings. */
+    ensureHomeWorkspace(): Workspace;
+    /**
+     * ensureHomeWorkspace creates home's records at startup, before any chat is known.
+     * This gives it its destination, once: an existing binding is never replaced.
+     * Callers decide what counts as home's chat — see Channel.isRootDM.
+     */
+    connectHomeWorkspace(chatId: string): boolean;
     workspaceByChat(chatId: string): Workspace | undefined;
     workspaceByName(name: string): Workspace | undefined;
+    listWorkspaces(): Workspace[];
     upsertWorkspace(ws: Workspace): void;
+    removeWorkspace(name: string): Workspace | undefined;
+    /** Persist the session ID without changing the saved model setting. */
     setSession(name: string, sessionId: string): void;
     clearSession(name: string): void;
+    setModel(name: string, model: string | undefined): void;
     setBehavior(name: string, behavior: "assistant" | "relay"): void;
+    addProject(project: Project): void;
+    listProjects(): Project[];
+    projectByName(name: string): Project | undefined;
+    removeProject(name: string): void;
+    listSchedules(): ScheduleEntry[];
+    addSchedule(entry: ScheduleEntry): void;
+    removeSchedule(id: string): void;
+    updateSchedule(id: string, update: Partial<Pick<ScheduleEntry, "enabled" | "cron" | "prompt" | "timezone">>): void;
     approveUser(userId: string, userName: string): void;
 }

package/dist/config.js

@@ -108,6 +108,8 @@ export class Config {
             authorizedUsers: (raw.authorizedUsers ?? []),
             pendingPairings: (raw.pendingPairings ?? []),
             workspaces: (raw.workspaces ?? []),
+            schedules: (raw.schedules ?? []),
+            projects: (raw.projects ?? []),
         };
     }
     write(data) {
@@ -142,6 +144,13 @@ export class Config {
     listUsers() {
         return this.read().authorizedUsers;
     }
+    /** All authorized IDs, including environment-configured and pairing-approved users. */
+    listAuthorizedUserIds() {
+        return [...new Set([
+                ...this.envUserIds,
+                ...this.listUsers().map((user) => user.id),
+            ])];
+    }
     /** env var IDs (in-memory) + pairing-approved users (hot-reload from disk) */
     isAuthorized(userId) {
         return this.envUserIds.has(userId) || this.hasUser(userId);
@@ -185,12 +194,59 @@ export class Config {
             .join("");
     }
     // --- Workspaces ---
+    /** Home exists before a chat is paired. Never replace an existing home's settings. */
+    ensureHomeWorkspace() {
+        fs.mkdirSync(this.homeWorkspacePath, { recursive: true });
+        const data = this.read();
+        let home = data.workspaces.find((ws) => ws.name === "default");
+        let changed = false;
+        if (!home) {
+            home = { name: "default", cwd: this.homeWorkspacePath, chat_id: null,
+                current_session_id: null, behavior: "assistant", description: "Personal assistant", project: "home" };
+            // Avoid adopting an unrelated project with a reserved home name.
+            if (data.projects.some((project) => project.name === "home" && project.main_workspace !== "default")) {
+                throw new Error('Project "home" already has another main workspace; rename it before creating home.');
+            }
+            data.workspaces.push(home);
+            changed = true;
+        }
+        if (!home.project) {
+            const existing = data.projects.find((project) => project.main_workspace === home.name);
+            home.project = existing?.name ?? "home";
+            if (data.projects.some((project) => project.name === home.project && project.main_workspace !== home.name)) {
+                throw new Error(`Project "${home.project}" already has another main workspace.`);
+            }
+            changed = true;
+        }
+        if (!data.projects.some((project) => project.name === home.project)) {
+            data.projects.push({ name: home.project, description: home.description ?? "Personal assistant", main_workspace: home.name });
+            changed = true;
+        }
+        if (changed)
+            this.write(data);
+        return home;
+    }
+    /**
+     * ensureHomeWorkspace creates home's records at startup, before any chat is known.
+     * This gives it its destination, once: an existing binding is never replaced.
+     * Callers decide what counts as home's chat — see Channel.isRootDM.
+     */
+    connectHomeWorkspace(chatId) {
+        const home = this.ensureHomeWorkspace();
+        if (home.chat_id || this.workspaceByChat(chatId))
+            return false;
+        this.upsertWorkspace({ ...home, chat_id: chatId });
+        return true;
+    }
     workspaceByChat(chatId) {
         return this.read().workspaces.find((ws) => ws.chat_id === chatId);
     }
     workspaceByName(name) {
         return this.read().workspaces.find((ws) => ws.name === name);
     }
+    listWorkspaces() {
+        return this.read().workspaces;
+    }
     upsertWorkspace(ws) {
         const data = this.read();
         const idx = data.workspaces.findIndex((w) => w.name === ws.name);
@@ -200,6 +256,16 @@ export class Config {
             data.workspaces.push(ws);
         this.write(data);
     }
+    removeWorkspace(name) {
+        const data = this.read();
+        const idx = data.workspaces.findIndex((w) => w.name === name);
+        if (idx < 0)
+            return undefined;
+        const [removed] = data.workspaces.splice(idx, 1);
+        this.write(data);
+        return removed;
+    }
+    /** Persist the session ID without changing the saved model setting. */
     setSession(name, sessionId) {
         const data = this.read();
         const ws = data.workspaces.find((w) => w.name === name);
@@ -213,6 +279,15 @@ export class Config {
         const ws = data.workspaces.find((w) => w.name === name);
         if (ws) {
             ws.current_session_id = null;
+            delete ws.engine_handoff;
+            this.write(data);
+        }
+    }
+    setModel(name, model) {
+        const data = this.read();
+        const ws = data.workspaces.find((w) => w.name === name);
+        if (ws) {
+            ws.model = model;
             this.write(data);
         }
     }
@@ -224,6 +299,49 @@ export class Config {
             this.write(data);
         }
     }
+    // --- Projects ---
+    addProject(project) {
+        const data = this.read();
+        const idx = data.projects.findIndex((p) => p.name === project.name);
+        if (idx >= 0)
+            data.projects[idx] = project;
+        else
+            data.projects.push(project);
+        this.write(data);
+    }
+    listProjects() {
+        return this.read().projects;
+    }
+    projectByName(name) {
+        return this.read().projects.find((p) => p.name === name);
+    }
+    removeProject(name) {
+        const data = this.read();
+        data.projects = data.projects.filter((p) => p.name !== name);
+        this.write(data);
+    }
+    // --- Schedules ---
+    listSchedules() {
+        return this.read().schedules;
+    }
+    addSchedule(entry) {
+        const data = this.read();
+        data.schedules.push(entry);
+        this.write(data);
+    }
+    removeSchedule(id) {
+        const data = this.read();
+        data.schedules = data.schedules.filter((s) => s.id !== id);
+        this.write(data);
+    }
+    updateSchedule(id, update) {
+        const data = this.read();
+        const entry = data.schedules.find((s) => s.id === id);
+        if (entry) {
+            Object.assign(entry, update);
+            this.write(data);
+        }
+    }
     // --- Approval ---
     approveUser(userId, userName) {
         this.addUser({ id: userId, name: userName, approvedAt: Date.now() });

package/dist/engine/acp.d.ts

@@ -1,9 +1,14 @@
-import type { SpawnConfig } from "./registry.js";
-import type { Engine, EngineEvent, RunTurnOpts, SessionInfo } from "../types.js";
+import type { AcpEngineDefinition } from "./registry.js";
+import type { Engine, EngineEvent, PlanUsageWindow, RunTurnOpts, SessionInfo, SessionHistoryOpts, SessionMessage } from "../types.js";
 export declare class AcpEngine implements Engine {
     readonly name: string;
     private readonly spawnConfig;
-    constructor(name: string, spawnConfig: SpawnConfig);
+    constructor(name: string, spawnConfig: AcpEngineDefinition);
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
-    listSessions(_cwd: string): Promise<SessionInfo[]>;
+    getSessionMessages(opts: SessionHistoryOpts): Promise<SessionMessage[]>;
+    listSessions(cwd: string): Promise<SessionInfo[]>;
+    /** Short-lived, read-only ACP queries share one deadline and always release the child. */
+    private readSessionData;
 }
+/** PR #334's provider extension. Never treat standard ACP used/size as plan usage. */
+export declare function codexPlanUsage(meta: unknown): PlanUsageWindow[];