@byokit/openclaw 0.14.4 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.15.0 (2026-10-17)
+
+- Dependency update: pins @byokit/secrets 0.5.2.
+- Dependency update: pins @byokit/seal 0.3.1.
+- Dependency update: pins @byokit/discover 0.8.4.
+- Dependency update: pins @byokit/accounts 0.25.0.
+
+- FEAT: turn on one chat channel. `channels.telegram: { token, allowFrom, member, onMessage }` (off by default) hands every Telegram direct message from the people you list to your app's `onMessage`, never to an engine agent: a message naming a helper, or a chat command such as `/new`, is just text for your handler. `kit.reply(chat, text)` answers the chat. Groups, chat commands and channel config writes stay off, and the bot token reaches the engine only as process env, never config, disk or logs. `fakeTelegram()` in `./testing` stands in for the Bot API.
+
+## 0.14.5 (2026-10-17)
+
+- FIX: adding a Go plan key that names no workspace (a bound service key the console refuses to list) now clears the standing workspace header before its probe, instead of carrying the previous workspace on its calls. A failed add's cleanup now drops the workspace header with the key, instead of leaving it behind for the next key.
+- FEAT: `kit.installPlugin(pluginId)` installs the external provider plugin a route needs (`readiness: 'needs_plugin'`, such as Z.AI's GLM Coding Plan routes) into the kit's own engine, at exactly the engine's version and with the pinned npm integrity (`engine/plugins.json`). The plugin joins `plugins.allow` across restarts and `routes()` then reports its routes ready, so `addKey` reaches the engine's key test. A version or integrity mismatch rejects with `PluginInstallError` (`code: 'version' | 'integrity'`) and installs nothing; discovery never installs. The GLM Coding Plan sign-ins are subscription; the plain Z.AI key rows stay API key (billed per use), explicit opt-in.
+- FIX: the install policy no longer blocks every `@openclaw/` npm plugin at its dependency-tree check; plugin installs are allowed only at a pinned spec and integrity.
+- FIX: `removeAccount` and a cancelled/failed `addAccount` no longer resolve while the removed agent is still on the roster. The engine answers `agents.delete` before its roster hot-reload applies (the same lag as after `agents.create`), so an immediate `agents.list` could still show the gone agent and a cancelled ChatGPT add flaked as "the cancelled agent is deleted". Both delete paths now wait until the roster drops the agent (`untilUnlisted`, the `untilListed` mirror: 25 ms poll, ~5 s bound, plain error naming the agent on timeout). The fake gateway's `rosterApplyMs` now lags the delete roster the same way for engine parity.
+- FIX: a Go plan key pasted over the link signs in with its workspace. The wizard sign-in listed no workspaces, so a key acting for several was refused on the activation probe and every run (403 Workspace selection is required). The sign-in now lists the key's workspaces the way `addKey` does (one used unasked; several asked through the same hidden paste; refused or unreadable listing fails before anything changes) and writes the pick as the provider header before activation.
+
 ## 0.14.4 (2026-10-17)
 
 - Dependency update: pins @byokit/relay 0.8.0.

package/README.md

@@ -430,6 +430,33 @@ Public live view/thumbnail APIs are model-free; source tests alone do not prove
 The opt-in physical fixture retains raw JPEG/control inputs before decoding, pipe chunk order, complete
 synthetic provider bodies and authoritative SQLite transcripts, including failures.
 
+## One chat channel (Telegram)
+
+Off by default. Turn it on and every Telegram message from the people you list reaches your app, never an engine
+agent: the kit claims each one before the engine dispatches it, so a message that names a helper, or a chat command
+such as `/new`, is just text for your handler. You decide who answers (Crewhouse: Chief) and reply with `kit.reply`.
+
+```ts
+import { OpenClawKit, type ChannelMessage } from '@byokit/openclaw';
+
+declare const stateDir: string, botToken: string, chiefThread: string;
+const kit: OpenClawKit = new OpenClawKit({ stateDir, channels: { telegram: {
+  token: botToken,              // from BotFather; the engine gets it as process env, never config, disk or logs
+  allowFrom: ['123456789'],     // numeric Telegram user ids; everyone else is dropped
+  member: 'm1',                 // the member your replies are sent as
+  onMessage: async ({ chat, text }: ChannelMessage) => {
+    const end = await kit.run({ member: 'm1', sessionKey: chiefThread, message: text }, () => {});
+    if (end.ok) await kit.reply(chat, end.text);
+  },
+} } });
+```
+
+Direct messages only: groups, chat commands, channel config writes and Telegram exec approvals stay off. `apiRoot`
+points the channel at a self-hosted Bot API server; tests use `fakeTelegram()` from `@byokit/openclaw/testing`, a
+loopback Bot API, so no bot or account is needed. An agent the gate lets run shell commands can read the token from
+the engine's environment, as it can the gateway token. Telegram is the only channel so far; another one will be a
+new key of `channels`.
+
 ## One config key, narrowed
 
 `patchConfig` is the only whole-config writer, and it can only start from `config.get`, whose result redacts

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { Approval, Decision, Member, RunRef, ToolHost, ToolSpec } from './types.ts';
+import type { Approval, ChannelMessage, Decision, Member, RunRef, ToolHost, ToolSpec } from './types.ts';
 /**
  * Asks must expire before the plugin's 195 s gate timeout, or the run gets a generic block while the approval
  * lingers (N3). The kit passes its `approvalTimeoutMs` through; anything above is clamped to this.
@@ -25,6 +25,7 @@ export declare function writePlugin(dir: string, o: {
     paramPrefix: string;
     gateBuiltins: boolean;
     browser?: boolean;
+    channels?: string[];
 }): void;
 export declare class Bridge {
     private readonly path;
@@ -37,6 +38,7 @@ export declare class Bridge {
     private readonly onAskGone;
     private readonly beforeAgentRun?;
     private readonly browserCapabilities?;
+    private readonly onChannelMessage?;
     private server?;
     private closing;
     private readonly sockets;
@@ -58,6 +60,7 @@ export declare class Bridge {
         onAskGone(id: string): void;
         beforeAgentRun?: (key: string, runId?: string) => Promise<boolean>;
         browserCapabilities?: () => readonly string[];
+        onChannelMessage?: (m: ChannelMessage) => void;
     });
     start(): Promise<void>;
     stop(): void;

package/dist/bridge.js

@@ -47,6 +47,8 @@ export function writePlugin(dir, o) {
         // true: engine builtins (web_fetch, memory, ...) are gated too, not only the app's tools.
         gateBuiltins: o.gateBuiltins,
         ...(o.browser ? { browser: true } : {}),
+        // The channels whose every inbound message the plugin claims for the app (5.18).
+        ...(o.channels?.length ? { channels: o.channels } : {}),
         tools: o.tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })),
     };
     for (const [file, data] of [['openclaw.plugin.json', manifest], ['tools.json', table]]) {
@@ -67,6 +69,7 @@ export class Bridge {
     onAskGone;
     beforeAgentRun;
     browserCapabilities;
+    onChannelMessage;
     server;
     closing = Promise.resolve();
     sockets = new Set();
@@ -90,6 +93,7 @@ export class Bridge {
         this.onAskGone = o.onAskGone;
         this.beforeAgentRun = o.beforeAgentRun;
         this.browserCapabilities = o.browserCapabilities;
+        this.onChannelMessage = o.onChannelMessage;
     }
     async start() {
         if (this.server)
@@ -270,6 +274,18 @@ export class Bridge {
                 .then(allow => this.reply(socket, { allow }), () => this.deny(socket, 'run unavailable'));
             return;
         }
+        if (message.kind === 'channel-message') {
+            const { channel, chat, from, text } = message;
+            if (!this.onChannelMessage || this.stopped || channel !== 'telegram' || typeof chat !== 'string' || !chat
+                || typeof from !== 'string' || typeof text !== 'string')
+                return this.deny(socket, 'channel unavailable');
+            this.reply(socket, { ok: true });
+            try {
+                this.onChannelMessage({ chat: { channel, id: chat }, from, text });
+            }
+            catch { /* the app's handler, not the engine's */ }
+            return;
+        }
         if (message.kind === 'gate')
             return void this.gate(socket, message);
         if (message.kind === 'call')

package/dist/config.d.ts

@@ -20,6 +20,7 @@ export declare function reconcileConfig(saved: object | undefined, o: {
         }>;
         tools: string[];
     };
+    channels?: KitOptions['channels'];
 }): object;
 /** Caller-owned task namespaces, including the engine key-agent rewrite; never an entire member. */
 export declare function appRecoveryPrefixes(ownership?: KitOptions['appOwnedSessions']): string[];

package/dist/config.js

@@ -46,6 +46,16 @@ export function reconcileConfig(saved, o) {
         models: { catalogRefresh: { enabled: false } }, logging: { file: join(o.stateDir, 'logs', 'openclaw-events.log') },
     });
     c.channels ??= {};
+    const telegram = o.channels?.telegram;
+    if (telegram) {
+        // The one channel the engine starts (5.18), written whole: no app key can widen who reaches it or where it routes.
+        // DMs only, from listed ids; no groups, chat commands, channel config writes or exec approvals. The bridge claims
+        // every message before dispatch, so these are the second wall. The token is process env, never this file.
+        c.channels = { telegram: { enabled: true, dmPolicy: 'allowlist', allowFrom: [...telegram.allowFrom],
+                groupPolicy: 'disabled', configWrites: false, commands: { native: false, nativeSkills: false },
+                execApprovals: { enabled: false }, ...(telegram.apiRoot ? { apiRoot: telegram.apiRoot } : {}) } };
+        c.commands = { ...object(c.commands) ? c.commands : {}, allowFrom: { ...c.commands?.allowFrom, telegram: [] } };
+    }
     c.agents ??= {};
     c.agents.defaults ??= {};
     // Auth isolation (5.15): left unset, the pin makes the first agent the inherited owner once the roster grows, and
@@ -87,7 +97,8 @@ export function reconcileConfig(saved, o) {
             // Plus every explicitly offered route the app names, so an opted-in sign-in (OpenRouter) is not blocked.
             ...offeredPlugins(o.offered),
             // Plus every external plugin the kit installed (B7): an app's own allow list must not disable it at the next boot.
-            ...o.plugins ?? []])];
+            ...o.plugins ?? [],
+            ...telegram ? ['telegram'] : []])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
     if (o.browser) {

package/dist/engine.d.ts

@@ -5,7 +5,7 @@ import type { KitState, ToolSpec } from './types.ts';
 /** The app's stateDir as an absolute path with no symlinked ancestor (macOS /tmp and /var are symlinks):
  * the native Claude login's accounts store refuses any other, so a relative or symlinked stateDir failed it. */
 export declare function canonicalStateDir(dir: string): string;
-export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'offered' | 'appOwnedSessions' | 'installPolicy' | 'log' | 'bridge' | 'authSeal'> & {
+export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'offered' | 'appOwnedSessions' | 'installPolicy' | 'log' | 'bridge' | 'authSeal' | 'channels'> & {
     pluginId: string;
     tools: ToolSpec[];
     gateBuiltins?: boolean;

package/dist/engine.js

@@ -286,12 +286,14 @@ export class Engine {
         }
         // The bridge manifest and tool table follow the app's tools on every prepare (O5).
         writePlugin(pluginDir, { id: this.o.pluginId, tools: this.o.tools, paramPrefix: this.paramPrefix,
-            gateBuiltins: this.o.gateBuiltins !== false, browser: !!this.o.browserConfig });
+            gateBuiltins: this.o.gateBuiltins !== false, browser: !!this.o.browserConfig,
+            channels: this.o.channels?.telegram ? ['telegram'] : [] });
         const path = join(this.root, 'openclaw.json');
         const saved = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
         const config = reconcileConfig(saved, { root: this.root, stateDir: this.o.stateDir, port: this.port, pluginId: this.o.pluginId,
             pluginDir, policyPath: join(kitDir, 'policy', 'policy.mjs'), app: this.o.config, offered: this.o.offered,
-            installPolicy: this.o.installPolicy, browser: this.o.browserConfig?.(), plugins: installedPlugins(this.root) });
+            installPolicy: this.o.installPolicy, browser: this.o.browserConfig?.(), plugins: installedPlugins(this.root),
+            channels: this.o.channels });
         putChanged(path, JSON.stringify(config, null, 2) + '\n');
     }
     /** B7: the engine's own installer for one pinned external plugin, in the isolated engine env with the kit's npm
@@ -508,6 +510,11 @@ export class Engine {
         }
         this.state('starting');
         const { entry, env } = this.doctorContext();
+        // A turned-on channel (5.18) starts in the gateway alone; doctor and installs keep channels off and never see the token.
+        if (this.o.channels?.telegram) {
+            delete env.OPENCLAW_SKIP_CHANNELS;
+            env.TELEGRAM_BOT_TOKEN = this.o.channels.telegram.token;
+        }
         const fd = openSync(join(this.o.stateDir, 'logs', 'openclaw.log'), 'a', 0o600);
         const usageDir = join(this.root, 'usage'), bootId = randomUUID();
         try {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';

package/dist/kit.d.ts

@@ -2,7 +2,7 @@ import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyHandle } from './keys.ts';
 import { type RouteView } from './routes.ts';
 import type { BrowserHost, BrowserOptions } from './browser.ts';
-import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
+import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ChannelChat, TelegramChannel, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -26,6 +26,9 @@ export type KitOptions = {
         keyPrefixes: string[];
     };
     browser?: BrowserOptions;
+    channels?: {
+        telegram?: TelegramChannel;
+    };
     installPolicy?: {
         trustedSkills: string;
         ownRoots: string[];
@@ -209,6 +212,8 @@ export declare class OpenClawKit {
     patchConfig(patch: object, o?: {
         agentId?: string;
     }): Promise<void>;
+    /** Answers one chat on a turned-on channel (5.18), through the engine's own outbound send. */
+    reply(chat: ChannelChat, text: string): Promise<void>;
     memoryLimited(member: Member): boolean;
     getConfigKey(key: string): unknown;
     setConfigKey(key: string, value: unknown): unknown;

package/dist/kit.js

@@ -1,4 +1,5 @@
 import { openCodeWorkspaces } from '@byokit/accounts/opencode-go';
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -647,6 +648,13 @@ export class OpenClawKit {
         if (o.browser && (!o.browser.executablePath.startsWith('/') || (o.browser.members !== 'all'
             && (!Array.isArray(o.browser.members) || o.browser.members.some(m => !MEMBER_ID.test(m) || m.startsWith(KEY_PREFIX))))))
             throw new Error('invalid browser options');
+        const telegram = o.channels?.telegram;
+        // The token never reaches an error, a log or the config (5.18).
+        if (telegram && (typeof telegram.token !== 'string' || !/^\d+:[\w-]+$/.test(telegram.token)
+            || !Array.isArray(telegram.allowFrom) || !telegram.allowFrom.length || telegram.allowFrom.some(id => typeof id !== 'string' || !/^\d+$/.test(id))
+            || typeof telegram.member !== 'string' || !MEMBER_ID.test(telegram.member) || telegram.member.startsWith(KEY_PREFIX)
+            || typeof telegram.onMessage !== 'function' || (telegram.apiRoot !== undefined && !/^https?:\/\/[^\s]+$/.test(telegram.apiRoot))))
+            throw new Error('invalid telegram channel options');
         // The engine lowercases and alias-maps a tool name before the gate hook sees it (bash -> exec, cron ->
         // automations); a name it would rewrite reaches the gate as a builtin, so refuse it here.
         for (const t of o.tools ?? []) {
@@ -711,6 +719,7 @@ export class OpenClawKit {
                 } } : {}),
             permitted: o.permitted ?? (() => true), approvalTimeoutMs: o.approvalTimeoutMs ?? 180_000,
             memberOf: (ref) => this.memberOf(ref),
+            ...(o.channels?.telegram ? { onChannelMessage: (m) => o.channels.telegram.onMessage(m) } : {}),
             onAsk: (a) => this.approvalsCtl.add(a), onAskGone: (id) => this.approvalsCtl.remove(id) });
         slot.bridge = this.bridge;
     }
@@ -1298,7 +1307,7 @@ export class OpenClawKit {
             port: Number(readFileSync(join(this.engine.root, 'port'), 'utf8')), pluginId: this.o.plugin?.id ?? 'byokit',
             pluginDir: join(this.engine.root, 'plugin'), policyPath: fileURLToPath(new URL('../policy/policy.mjs', import.meta.url)), app: patch,
             offered: this.o.offered, installPolicy: this.o.installPolicy, plugins: installedPlugins(this.engine.root),
-            ...(this.o.browser ? { browser: this.browserConfig() } : {}) });
+            ...(this.o.browser ? { browser: this.browserConfig() } : {}), channels: this.o.channels });
         if (this.o.browser && !browserToolPolicySafe(safe, this.toolNames()))
             throw new Error('browser tool policy refused');
         if (this.o.browser) {
@@ -1308,6 +1317,16 @@ export class OpenClawKit {
         }
         await this.request()('config.patch', { raw: JSON.stringify(safe), baseHash: response.hash, ...(o?.agentId ? { agentId: o.agentId } : {}) });
     }
+    /** Answers one chat on a turned-on channel (5.18), through the engine's own outbound send. */
+    async reply(chat, text) {
+        if (chat?.channel !== 'telegram' || !this.o.channels?.telegram)
+            throw new Error(`channel is not turned on: ${String(chat?.channel)}`);
+        if (typeof chat.id !== 'string' || !chat.id || typeof text !== 'string' || !text)
+            throw new Error('reply needs a chat and text');
+        // The engine needs one owning agent for an outbound send once several exist; the reply is the member's.
+        const { agentId } = await this.ensureMember(this.o.channels.telegram.member);
+        await this.request()('send', { channel: chat.channel, to: chat.id, message: text, agentId, idempotencyKey: randomUUID() });
+    }
     memoryLimited(member) {
         const config = JSON.parse(readFileSync(join(this.engine.root, 'openclaw.json'), 'utf8'));
         return configMemoryLimited(config, member);

package/dist/testing/fake-telegram.d.ts

@@ -0,0 +1,19 @@
+export type FakeTelegramCall = {
+    method: string;
+    body: Record<string, unknown>;
+};
+export type FakeTelegram = {
+    url: string;
+    calls: FakeTelegramCall[];
+    sent: {
+        chat: string;
+        text: string;
+    }[];
+    /** Queues one private message from user `from` to the bot; the next getUpdates returns it. */
+    message(from: string, text: string): void;
+    close(): Promise<void>;
+};
+export declare function fakeTelegram(o: {
+    token: string;
+    username?: string;
+}): Promise<FakeTelegram>;

package/dist/testing/fake-telegram.js

@@ -0,0 +1,72 @@
+// A loopback Telegram Bot API (5.18): the engine's Telegram channel long-polls it exactly as it would
+// api.telegram.org, so a channel test needs no bot, no account and no network. Point `channels.telegram.apiRoot`
+// at `url`. Only the token it was made with is accepted; every other token answers 401 as Telegram does.
+import { createServer } from 'node:http';
+export function fakeTelegram(o) {
+    const calls = [], sent = [];
+    const updates = [];
+    let waiters = [];
+    let nextUpdate = 1, nextMessage = 1;
+    const wake = () => { const w = waiters; waiters = []; for (const fn of w)
+        fn(); };
+    const server = createServer((req, res) => {
+        let raw = '';
+        req.on('data', chunk => { raw += chunk; });
+        req.on('end', async () => {
+            const answer = (status, body) => {
+                if (res.writableEnded)
+                    return;
+                res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+            };
+            const match = /^\/bot([^/]+)\/([A-Za-z]+)$/.exec(new URL(req.url ?? '/', 'http://x').pathname);
+            if (!match || match[1] !== o.token)
+                return answer(401, { ok: false, error_code: 401, description: 'Unauthorized' });
+            let body = {};
+            try {
+                body = raw ? JSON.parse(raw) : {};
+            }
+            catch { /* a form body: no fields this fake reads */ }
+            const method = match[2];
+            calls.push({ method, body });
+            const ok = (result) => answer(200, { ok: true, result });
+            if (method === 'getMe')
+                return ok({ id: 7000001, is_bot: true, first_name: 'Chief', username: o.username ?? 'byokit_test_bot',
+                    can_join_groups: false, can_read_all_group_messages: false, supports_inline_queries: false });
+            if (method === 'sendMessage') {
+                const chat = String(body.chat_id), text = String(body.text ?? '');
+                sent.push({ chat, text });
+                return ok({ message_id: nextMessage++, date: Math.floor(Date.now() / 1000), chat: { id: Number(chat), type: 'private' }, text });
+            }
+            if (method === 'getUpdates') {
+                const offset = Number(body.offset ?? 0);
+                const pending = () => updates.filter(u => u.update_id >= offset);
+                if (!pending().length && Number(body.timeout ?? 0) > 0) {
+                    await new Promise(resolve => {
+                        const timer = setTimeout(resolve, Math.min(Number(body.timeout), 30) * 1000);
+                        waiters.push(() => { clearTimeout(timer); resolve(); });
+                    });
+                }
+                return ok(pending());
+            }
+            // deleteWebhook, setMyCommands, sendChatAction, ...: accepted with nothing to report.
+            return ok(true);
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = address && typeof address !== 'string' ? address.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`, calls, sent,
+                message(from, text) {
+                    const id = Number(from), date = Math.floor(Date.now() / 1000);
+                    updates.push({ update_id: nextUpdate++, message: { message_id: nextMessage++, date, text,
+                            chat: { id, type: 'private', first_name: 'Umer' }, from: { id, is_bot: false, first_name: 'Umer' } } });
+                    wake();
+                },
+                close: () => new Promise(done => { wake(); server.closeAllConnections(); server.close(() => done()); }),
+            });
+        });
+    });
+}

package/dist/testing/index.d.ts

@@ -2,3 +2,4 @@ export { fakeGateway, type FakeGateway, type FakeHandler, type FakeParams, type
 export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore, type FakeBrowserHost, type FakeBrowserHostOptions, type BrowserFixture } from './browser.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
 export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall, type StubRequest } from './model-stub.ts';
+export { fakeTelegram, type FakeTelegram, type FakeTelegramCall } from './fake-telegram.ts';

package/dist/testing/index.js

@@ -3,3 +3,4 @@ export { fakeGateway } from './fake-gateway.js';
 export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore } from './browser.js';
 export { openclawContract } from './contract.js';
 export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls } from './model-stub.js';
+export { fakeTelegram } from './fake-telegram.js';

package/dist/types.d.ts

@@ -258,6 +258,25 @@ export type CallOptions = {
     timeoutMs?: number | null;
     signal?: AbortSignal;
 };
+/** A chat on a channel the kit turned on (5.18): `id` is the channel's own chat id. `kit.reply` takes it back. */
+export type ChannelChat = {
+    channel: 'telegram';
+    id: string;
+};
+/** One inbound channel message. The kit claims it before the engine dispatches, so no agent runs from a channel. */
+export type ChannelMessage = {
+    chat: ChannelChat;
+    from: string;
+    text: string;
+};
+/** `KitOptions.channels.telegram` (5.18): a bot's direct messages from listed people, handed to the app only. */
+export type TelegramChannel = {
+    token: string;
+    allowFrom: readonly string[];
+    member: Member;
+    apiRoot?: string;
+    onMessage(message: ChannelMessage): void;
+};
 /** Kit-owned invalidation only: no origin, URL, input value or lease secret. */
 export type BrowserPing = {
     member: Member;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -60,12 +60,12 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/accounts": "0.24.3",
+    "@byokit/accounts": "0.25.0",
     "@byokit/pair": "0.10.2",
     "@byokit/relay": "0.8.0",
-    "@byokit/discover": "0.8.3",
-    "@byokit/seal": "0.3.0",
-    "@byokit/secrets": "0.5.1",
+    "@byokit/discover": "0.8.4",
+    "@byokit/seal": "0.3.1",
+    "@byokit/secrets": "0.5.2",
     "@openclaw/gateway-client": "2026.8.35",
     "@openclaw/gateway-protocol": "2026.8.35",
     "ws": "8.22.0"

package/plugin/index.js

@@ -18,6 +18,7 @@ const TOOLS = new Map(table.tools.map((t) => [t.name, t]));
 // Absent (a table from before the flag) reads as true: fail closed.
 const GATE_BUILTINS = table.gateBuiltins !== false;
 const BROWSER = table.browser === true;
+const CHANNELS = new Set(table.channels ?? []);
 let browserCapabilities = [];
 function scrubBrowserCapabilities(value) {
   let serialized = JSON.stringify(value).replace(/\b(?:wss?|https?):\/\/[^\s"'<>\\]+/g, url => {
@@ -167,6 +168,15 @@ export default {
       api.on('tool_result_persist', event => ({ message: scrubBrowserCapabilities(event.message) }));
       api.on('before_message_write', event => ({ message: scrubBrowserCapabilities(event.message) }));
     }
+    // A turned-on channel's messages belong to the app (5.18): claim each one before the engine dispatches it to any
+    // agent, hand it to the host without waiting, and stay claimed when the host is gone, so no agent ever runs from it.
+    if (CHANNELS.size) api.on('before_dispatch', (event, ctx) => {
+      const channel = ctx?.channelId ?? event?.channel;
+      if (!CHANNELS.has(channel)) return undefined;
+      void bridgeRequest({ kind: 'channel-message', channel, chat: ctx?.conversationId, from: event?.senderId ?? ctx?.senderId,
+        text: event?.content }, { timeoutMs: 10_000 }).catch(() => {});
+      return { handled: true };
+    });
     for (const spec of table.tools) {
       api.registerTool({
         name: spec.name,