opencode-gateway 0.1.0

package/dist/telegram/runtime.js

@@ -0,0 +1,133 @@
+import { formatUnixMsAsUtc } from "../tools/time";
+import { formatError } from "../utils/error";
+import { readTelegramHealthSnapshot, recordTelegramProbeFailure, recordTelegramProbeSuccess, recordTelegramSendFailure, } from "./state";
+export class GatewayTelegramRuntime {
+    client;
+    delivery;
+    store;
+    logger;
+    config;
+    polling;
+    opencodeEvents;
+    constructor(client, delivery, store, logger, config, polling, opencodeEvents) {
+        this.client = client;
+        this.delivery = delivery;
+        this.store = store;
+        this.logger = logger;
+        this.config = config;
+        this.polling = polling;
+        this.opencodeEvents = opencodeEvents;
+    }
+    isEnabled() {
+        return this.config.enabled;
+    }
+    isPolling() {
+        return this.polling?.isRunning() ?? false;
+    }
+    allowlistMode() {
+        return this.config.enabled ? "explicit" : "disabled";
+    }
+    start() {
+        this.polling?.start();
+    }
+    async status() {
+        const snapshot = readTelegramHealthSnapshot(this.store);
+        if (!this.config.enabled || this.client === null) {
+            return {
+                ...snapshot,
+                enabled: false,
+                polling: false,
+                allowlistMode: "disabled",
+                allowedChatsCount: 0,
+                allowedUsersCount: 0,
+                liveProbe: "disabled",
+                liveProbeError: null,
+                liveBotId: null,
+                liveBotUsername: null,
+                streamingEnabled: false,
+                opencodeEventStreamConnected: this.opencodeEvents.isConnected(),
+                lastEventStreamError: this.opencodeEvents.lastStreamError(),
+            };
+        }
+        try {
+            const bot = await this.client.getMe();
+            const recordedAtMs = Date.now();
+            recordTelegramProbeSuccess(this.store, bot, recordedAtMs);
+            return buildEnabledStatus(this.config, readTelegramHealthSnapshot(this.store), this.isPolling(), "ok", null, bot, this.opencodeEvents);
+        }
+        catch (error) {
+            const message = formatError(error);
+            const recordedAtMs = Date.now();
+            recordTelegramProbeFailure(this.store, message, recordedAtMs);
+            this.logger.log("warn", `telegram live probe failed: ${message}`);
+            return buildEnabledStatus(this.config, readTelegramHealthSnapshot(this.store), this.isPolling(), "failed", message, null, this.opencodeEvents);
+        }
+    }
+    async sendTest(chatId, topic, text, mode) {
+        const normalizedChatId = normalizeRequiredField(chatId, "chat_id");
+        const normalizedTopic = normalizeOptionalField(topic);
+        const body = normalizeOptionalField(text) ?? defaultTestMessage();
+        if (!this.config.enabled || this.client === null) {
+            throw new Error("telegram is not enabled");
+        }
+        try {
+            const sentAtMs = Date.now();
+            const result = await this.delivery.sendTest({
+                channel: "telegram",
+                target: normalizedChatId,
+                topic: normalizedTopic,
+            }, body, mode);
+            if (!result.delivered) {
+                throw new Error("telegram test delivery produced no final message");
+            }
+            return {
+                chatId: normalizedChatId,
+                topic: normalizedTopic,
+                text: body,
+                sentAtMs,
+                mode: result.mode,
+            };
+        }
+        catch (error) {
+            const message = formatError(error);
+            recordTelegramSendFailure(this.store, message, Date.now());
+            this.logger.log("warn", `telegram_send_test failed: ${message}`);
+            throw error;
+        }
+    }
+}
+function buildEnabledStatus(config, snapshot, polling, liveProbe, liveProbeError, bot, opencodeEvents) {
+    return {
+        ...snapshot,
+        enabled: true,
+        polling,
+        allowlistMode: "explicit",
+        allowedChatsCount: config.allowedChats.length,
+        allowedUsersCount: config.allowedUsers.length,
+        liveProbe,
+        liveProbeError,
+        liveBotId: bot ? String(bot.id) : null,
+        liveBotUsername: bot?.username ?? null,
+        streamingEnabled: true,
+        opencodeEventStreamConnected: opencodeEvents.isConnected(),
+        lastEventStreamError: opencodeEvents.lastStreamError(),
+    };
+}
+function normalizeRequiredField(value, field) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} must not be empty`);
+    }
+    return trimmed;
+}
+function normalizeOptionalField(value) {
+    if (value === null) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}
+function defaultTestMessage() {
+    const recordedAtMs = Date.now();
+    return `opencode-gateway telegram_send_test at ${formatUnixMsAsUtc(recordedAtMs)}`;
+}

package/dist/telegram/state.d.ts

@@ -0,0 +1,36 @@
+import type { SqliteStore } from "../store/sqlite";
+import type { TelegramBotProfile, TelegramChatType } from "./types";
+export type TelegramStreamingFallbackReason = "non_private_chat" | "progressive_handle_unavailable" | "draft_send_failed" | "preview_not_established";
+export type TelegramHealthSnapshot = {
+    updateOffset: number | null;
+    lastPollSuccessMs: number | null;
+    lastPollErrorAtMs: number | null;
+    lastPollErrorMessage: string | null;
+    lastSendSuccessMs: number | null;
+    lastSendErrorAtMs: number | null;
+    lastSendErrorMessage: string | null;
+    lastProbeSuccessMs: number | null;
+    lastProbeErrorAtMs: number | null;
+    lastProbeErrorMessage: string | null;
+    lastBotId: string | null;
+    lastBotUsername: string | null;
+    lastDraftSuccessMs: number | null;
+    lastDraftErrorAtMs: number | null;
+    lastDraftErrorMessage: string | null;
+    lastPreviewEmitMs: number | null;
+    lastStreamFallbackAtMs: number | null;
+    lastStreamFallbackReason: TelegramStreamingFallbackReason | null;
+};
+export declare function readTelegramHealthSnapshot(store: SqliteStore): TelegramHealthSnapshot;
+export declare function recordTelegramPollSuccess(store: SqliteStore, recordedAtMs: number): void;
+export declare function recordTelegramPollFailure(store: SqliteStore, message: string, recordedAtMs: number): void;
+export declare function recordTelegramSendSuccess(store: SqliteStore, recordedAtMs: number): void;
+export declare function recordTelegramSendFailure(store: SqliteStore, message: string, recordedAtMs: number): void;
+export declare function recordTelegramProbeSuccess(store: SqliteStore, bot: TelegramBotProfile, recordedAtMs: number): void;
+export declare function recordTelegramProbeFailure(store: SqliteStore, message: string, recordedAtMs: number): void;
+export declare function recordTelegramDraftSuccess(store: SqliteStore, recordedAtMs: number): void;
+export declare function recordTelegramDraftFailure(store: SqliteStore, message: string, recordedAtMs: number): void;
+export declare function recordTelegramPreviewEmit(store: SqliteStore, recordedAtMs: number): void;
+export declare function recordTelegramStreamFallback(store: SqliteStore, reason: TelegramStreamingFallbackReason, recordedAtMs: number): void;
+export declare function readTelegramChatType(store: SqliteStore, chatId: string): TelegramChatType | null;
+export declare function recordTelegramChatType(store: SqliteStore, chatId: string, chatType: TelegramChatType, recordedAtMs: number): void;

package/dist/telegram/state.js

@@ -0,0 +1,128 @@
+const TELEGRAM_UPDATE_OFFSET_KEY = "telegram.update_offset";
+const TELEGRAM_LAST_POLL_SUCCESS_MS_KEY = "telegram.last_poll_success_ms";
+const TELEGRAM_LAST_POLL_ERROR_AT_MS_KEY = "telegram.last_poll_error_at_ms";
+const TELEGRAM_LAST_POLL_ERROR_MESSAGE_KEY = "telegram.last_poll_error_message";
+const TELEGRAM_LAST_SEND_SUCCESS_MS_KEY = "telegram.last_send_success_ms";
+const TELEGRAM_LAST_SEND_ERROR_AT_MS_KEY = "telegram.last_send_error_at_ms";
+const TELEGRAM_LAST_SEND_ERROR_MESSAGE_KEY = "telegram.last_send_error_message";
+const TELEGRAM_LAST_PROBE_SUCCESS_MS_KEY = "telegram.last_probe_success_ms";
+const TELEGRAM_LAST_PROBE_ERROR_AT_MS_KEY = "telegram.last_probe_error_at_ms";
+const TELEGRAM_LAST_PROBE_ERROR_MESSAGE_KEY = "telegram.last_probe_error_message";
+const TELEGRAM_LAST_BOT_ID_KEY = "telegram.last_bot_id";
+const TELEGRAM_LAST_BOT_USERNAME_KEY = "telegram.last_bot_username";
+const TELEGRAM_LAST_DRAFT_SUCCESS_MS_KEY = "telegram.last_draft_success_ms";
+const TELEGRAM_LAST_DRAFT_ERROR_AT_MS_KEY = "telegram.last_draft_error_at_ms";
+const TELEGRAM_LAST_DRAFT_ERROR_MESSAGE_KEY = "telegram.last_draft_error_message";
+const TELEGRAM_LAST_PREVIEW_EMIT_MS_KEY = "telegram.last_preview_emit_ms";
+const TELEGRAM_LAST_STREAM_FALLBACK_AT_MS_KEY = "telegram.last_stream_fallback_at_ms";
+const TELEGRAM_LAST_STREAM_FALLBACK_REASON_KEY = "telegram.last_stream_fallback_reason";
+export function readTelegramHealthSnapshot(store) {
+    return {
+        updateOffset: readStoredInteger(store, TELEGRAM_UPDATE_OFFSET_KEY),
+        lastPollSuccessMs: readStoredInteger(store, TELEGRAM_LAST_POLL_SUCCESS_MS_KEY),
+        lastPollErrorAtMs: readStoredInteger(store, TELEGRAM_LAST_POLL_ERROR_AT_MS_KEY),
+        lastPollErrorMessage: readStoredText(store, TELEGRAM_LAST_POLL_ERROR_MESSAGE_KEY),
+        lastSendSuccessMs: readStoredInteger(store, TELEGRAM_LAST_SEND_SUCCESS_MS_KEY),
+        lastSendErrorAtMs: readStoredInteger(store, TELEGRAM_LAST_SEND_ERROR_AT_MS_KEY),
+        lastSendErrorMessage: readStoredText(store, TELEGRAM_LAST_SEND_ERROR_MESSAGE_KEY),
+        lastProbeSuccessMs: readStoredInteger(store, TELEGRAM_LAST_PROBE_SUCCESS_MS_KEY),
+        lastProbeErrorAtMs: readStoredInteger(store, TELEGRAM_LAST_PROBE_ERROR_AT_MS_KEY),
+        lastProbeErrorMessage: readStoredText(store, TELEGRAM_LAST_PROBE_ERROR_MESSAGE_KEY),
+        lastBotId: readStoredText(store, TELEGRAM_LAST_BOT_ID_KEY),
+        lastBotUsername: readStoredText(store, TELEGRAM_LAST_BOT_USERNAME_KEY),
+        lastDraftSuccessMs: readStoredInteger(store, TELEGRAM_LAST_DRAFT_SUCCESS_MS_KEY),
+        lastDraftErrorAtMs: readStoredInteger(store, TELEGRAM_LAST_DRAFT_ERROR_AT_MS_KEY),
+        lastDraftErrorMessage: readStoredText(store, TELEGRAM_LAST_DRAFT_ERROR_MESSAGE_KEY),
+        lastPreviewEmitMs: readStoredInteger(store, TELEGRAM_LAST_PREVIEW_EMIT_MS_KEY),
+        lastStreamFallbackAtMs: readStoredInteger(store, TELEGRAM_LAST_STREAM_FALLBACK_AT_MS_KEY),
+        lastStreamFallbackReason: readStoredFallbackReason(store),
+    };
+}
+export function recordTelegramPollSuccess(store, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_POLL_SUCCESS_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_POLL_ERROR_AT_MS_KEY, "", recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_POLL_ERROR_MESSAGE_KEY, "", recordedAtMs);
+}
+export function recordTelegramPollFailure(store, message, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_POLL_ERROR_AT_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_POLL_ERROR_MESSAGE_KEY, message, recordedAtMs);
+}
+export function recordTelegramSendSuccess(store, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_SEND_SUCCESS_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_SEND_ERROR_AT_MS_KEY, "", recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_SEND_ERROR_MESSAGE_KEY, "", recordedAtMs);
+}
+export function recordTelegramSendFailure(store, message, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_SEND_ERROR_AT_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_SEND_ERROR_MESSAGE_KEY, message, recordedAtMs);
+}
+export function recordTelegramProbeSuccess(store, bot, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_PROBE_SUCCESS_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_PROBE_ERROR_AT_MS_KEY, "", recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_PROBE_ERROR_MESSAGE_KEY, "", recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_BOT_ID_KEY, String(bot.id), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_BOT_USERNAME_KEY, bot.username ?? "", recordedAtMs);
+}
+export function recordTelegramProbeFailure(store, message, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_PROBE_ERROR_AT_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_PROBE_ERROR_MESSAGE_KEY, message, recordedAtMs);
+}
+export function recordTelegramDraftSuccess(store, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_DRAFT_SUCCESS_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_DRAFT_ERROR_AT_MS_KEY, "", recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_DRAFT_ERROR_MESSAGE_KEY, "", recordedAtMs);
+}
+export function recordTelegramDraftFailure(store, message, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_DRAFT_ERROR_AT_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_DRAFT_ERROR_MESSAGE_KEY, message, recordedAtMs);
+}
+export function recordTelegramPreviewEmit(store, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_PREVIEW_EMIT_MS_KEY, String(recordedAtMs), recordedAtMs);
+}
+export function recordTelegramStreamFallback(store, reason, recordedAtMs) {
+    store.putStateValue(TELEGRAM_LAST_STREAM_FALLBACK_AT_MS_KEY, String(recordedAtMs), recordedAtMs);
+    store.putStateValue(TELEGRAM_LAST_STREAM_FALLBACK_REASON_KEY, reason, recordedAtMs);
+}
+export function readTelegramChatType(store, chatId) {
+    const value = readStoredText(store, telegramChatTypeKey(chatId));
+    return value === null ? null : value;
+}
+export function recordTelegramChatType(store, chatId, chatType, recordedAtMs) {
+    store.putStateValue(telegramChatTypeKey(chatId), chatType, recordedAtMs);
+}
+function telegramChatTypeKey(chatId) {
+    return `telegram.chat_type:${chatId}`;
+}
+function readStoredInteger(store, key) {
+    const value = store.getStateValue(key);
+    if (value === null || value.length === 0) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new Error(`stored ${key} is invalid: ${value}`);
+    }
+    return parsed;
+}
+function readStoredText(store, key) {
+    const value = store.getStateValue(key);
+    if (value === null || value.length === 0) {
+        return null;
+    }
+    return value;
+}
+function readStoredFallbackReason(store) {
+    const value = readStoredText(store, TELEGRAM_LAST_STREAM_FALLBACK_REASON_KEY);
+    if (value === null) {
+        return null;
+    }
+    switch (value) {
+        case "non_private_chat":
+        case "progressive_handle_unavailable":
+        case "draft_send_failed":
+        case "preview_not_established":
+            return value;
+        default:
+            throw new Error(`stored ${TELEGRAM_LAST_STREAM_FALLBACK_REASON_KEY} is invalid: ${value}`);
+    }
+}

package/dist/telegram/types.d.ts

@@ -0,0 +1,80 @@
+export type TelegramApiResponse<Result> = {
+    ok: true;
+    result: Result;
+} | {
+    ok: false;
+    description?: string;
+    error_code?: number;
+};
+export type TelegramUpdate = {
+    update_id: number;
+    message?: TelegramMessage;
+    callback_query?: TelegramCallbackQuery;
+};
+export type TelegramMessage = {
+    message_id: number;
+    message_thread_id?: number;
+    text?: string;
+    caption?: string;
+    photo?: TelegramPhotoSize[];
+    document?: TelegramDocument;
+    from?: TelegramUser;
+    chat: TelegramChat;
+};
+export type TelegramCallbackQuery = {
+    id: string;
+    from: TelegramUser;
+    data?: string;
+    message?: TelegramCallbackMessage;
+};
+export type TelegramCallbackMessage = {
+    message_id: number;
+    message_thread_id?: number;
+    chat: TelegramChat;
+};
+export type TelegramPhotoSize = {
+    file_id: string;
+    file_unique_id?: string;
+    width: number;
+    height: number;
+    file_size?: number;
+};
+export type TelegramDocument = {
+    file_id: string;
+    file_unique_id?: string;
+    file_name?: string;
+    mime_type?: string;
+    file_size?: number;
+};
+export type TelegramUser = {
+    id: number;
+    is_bot?: boolean;
+    username?: string;
+    can_join_groups?: boolean;
+    can_read_all_group_messages?: boolean;
+    supports_inline_queries?: boolean;
+};
+export type TelegramChat = {
+    id: number;
+    type: string;
+};
+export type TelegramChatType = TelegramChat["type"];
+export type TelegramBotProfile = TelegramUser & {
+    is_bot: true;
+};
+export type TelegramFileRecord = {
+    file_id: string;
+    file_unique_id?: string;
+    file_size?: number;
+    file_path?: string;
+};
+export type TelegramInlineKeyboardButton = {
+    text: string;
+    callback_data: string;
+};
+export type TelegramInlineKeyboardMarkup = {
+    inline_keyboard: TelegramInlineKeyboardButton[][];
+};
+export type TelegramSentMessage = {
+    message_id: number;
+};

package/dist/telegram/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/channel-new-session.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewaySessionContext } from "../session/context";
+import type { ChannelSessionSwitcher } from "../session/switcher";
+export declare function createChannelNewSessionTool(switcher: Pick<ChannelSessionSwitcher, "createAndSwitchSession">, sessions: GatewaySessionContext): ToolDefinition;

package/dist/tools/channel-new-session.js

@@ -0,0 +1,27 @@
+import { tool } from "@opencode-ai/plugin";
+import { resolveToolDeliveryTarget } from "./channel-target";
+export function createChannelNewSessionTool(switcher, sessions) {
+    return tool({
+        description: "Create a fresh OpenCode session for a channel route and switch future inbound messages to it. When called from a channel-backed session, channel, target, and topic default to the current reply target.",
+        args: {
+            channel: tool.schema.string().min(1).optional(),
+            target: tool.schema.string().min(1).optional(),
+            topic: tool.schema.string().optional(),
+            title: tool.schema.string().optional(),
+        },
+        async execute(args, context) {
+            return formatChannelSessionSwitchResult(await switcher.createAndSwitchSession(resolveToolDeliveryTarget(args, context.sessionID, sessions), args.title ?? null));
+        },
+    });
+}
+function formatChannelSessionSwitchResult(result) {
+    return [
+        `channel=${result.channel}`,
+        `target=${result.target}`,
+        `topic=${result.topic ?? "none"}`,
+        `conversation_key=${result.conversationKey}`,
+        `previous_session_id=${result.previousSessionId ?? "none"}`,
+        `new_session_id=${result.newSessionId}`,
+        `effective_on=${result.effectiveOn}`,
+    ].join("\n");
+}

package/dist/tools/channel-send-file.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { ChannelFileSendResult } from "../host/file-sender";
+import type { GatewaySessionContext } from "../session/context";
+import { resolveToolDeliveryTarget } from "./channel-target";
+export declare function createChannelSendFileTool(sender: ChannelFileSenderLike, sessions: GatewaySessionContext): ToolDefinition;
+type ChannelFileSenderLike = {
+    sendFile(target: ReturnType<typeof resolveToolDeliveryTarget>, filePath: string, caption: string | null): Promise<ChannelFileSendResult>;
+};
+export {};

package/dist/tools/channel-send-file.js

@@ -0,0 +1,27 @@
+import { tool } from "@opencode-ai/plugin";
+import { resolveToolDeliveryTarget } from "./channel-target";
+export function createChannelSendFileTool(sender, sessions) {
+    return tool({
+        description: "Send a local absolute-path file to a channel target. When called from a channel-backed session, channel, target, and topic default to the current reply target.",
+        args: {
+            channel: tool.schema.string().min(1).optional(),
+            target: tool.schema.string().min(1).optional(),
+            topic: tool.schema.string().optional(),
+            file_path: tool.schema.string().min(1),
+            caption: tool.schema.string().optional(),
+        },
+        async execute(args, context) {
+            return formatChannelFileSendResult(await sender.sendFile(resolveToolDeliveryTarget(args, context.sessionID, sessions), args.file_path, args.caption ?? null));
+        },
+    });
+}
+function formatChannelFileSendResult(result) {
+    return [
+        `channel=${result.channel}`,
+        `target=${result.target}`,
+        `topic=${result.topic ?? "none"}`,
+        `file_path=${result.filePath}`,
+        `mime_type=${result.mimeType}`,
+        `delivery_kind=${result.deliveryKind}`,
+    ].join("\n");
+}

package/dist/tools/channel-target.d.ts

@@ -0,0 +1,7 @@
+import type { BindingDeliveryTarget } from "../binding";
+import type { GatewaySessionContext } from "../session/context";
+export declare function resolveToolDeliveryTarget(args: {
+    channel?: string;
+    target?: string;
+    topic?: string;
+}, sessionId: string | null | undefined, sessions: GatewaySessionContext): BindingDeliveryTarget;

package/dist/tools/channel-target.js

@@ -0,0 +1,28 @@
+export function resolveToolDeliveryTarget(args, sessionId, sessions) {
+    const fallback = sessionId ? sessions.getDefaultReplyTarget(sessionId) : null;
+    const channel = normalizeRequired(args.channel ?? fallback?.channel ?? null, "channel");
+    const target = normalizeRequired(args.target ?? fallback?.target ?? null, "target");
+    const topic = normalizeOptional(args.topic ?? fallback?.topic ?? null);
+    return {
+        channel,
+        target,
+        topic,
+    };
+}
+function normalizeRequired(value, field) {
+    if (value === null) {
+        throw new Error(`${field} is required when the current session has no default reply target`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} must not be empty`);
+    }
+    return trimmed;
+}
+function normalizeOptional(value) {
+    if (value === null) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}

package/dist/tools/cron-list.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayCronRuntime } from "../cron/runtime";
+export declare function createCronListTool(runtime: GatewayCronRuntime): ToolDefinition;

package/dist/tools/cron-list.js

@@ -0,0 +1,34 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatUnixMsAsUtc, formatUnixMsInTimeZone } from "./time";
+export function createCronListTool(runtime) {
+    return tool({
+        description: "List persisted gateway cron jobs. Schedules use cron.timezone or the runtime local time zone.",
+        args: {},
+        async execute() {
+            const jobs = runtime.listJobs();
+            if (jobs.length === 0) {
+                return "no cron jobs";
+            }
+            return jobs.map((job) => formatCronJob(job, runtime.timeZone())).join("\n\n");
+        },
+    });
+}
+function formatCronJob(job, timeZone) {
+    return [
+        `id=${job.id}`,
+        `enabled=${job.enabled}`,
+        `schedule=${job.schedule}`,
+        `timezone=${timeZone}`,
+        `next_run_at_ms=${job.nextRunAtMs}`,
+        `next_run_at_local=${formatUnixMsInTimeZone(job.nextRunAtMs, timeZone)}`,
+        `next_run_at_utc=${formatUnixMsAsUtc(job.nextRunAtMs)}`,
+        `delivery=${formatDelivery(job.deliveryChannel, job.deliveryTarget, job.deliveryTopic)}`,
+        `prompt=${job.prompt}`,
+    ].join("\n");
+}
+function formatDelivery(channel, target, topic) {
+    if (channel === null || target === null) {
+        return "none";
+    }
+    return topic === null ? `${channel}:${target}` : `${channel}:${target}:topic:${topic}`;
+}

package/dist/tools/cron-remove.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayCronRuntime } from "../cron/runtime";
+export declare function createCronRemoveTool(runtime: GatewayCronRuntime): ToolDefinition;

package/dist/tools/cron-remove.js

@@ -0,0 +1,12 @@
+import { tool } from "@opencode-ai/plugin";
+export function createCronRemoveTool(runtime) {
+    return tool({
+        description: "Remove a persisted gateway cron job",
+        args: {
+            id: tool.schema.string().min(1),
+        },
+        async execute(args) {
+            return runtime.removeJob(args.id) ? `removed=${args.id}` : `missing=${args.id}`;
+        },
+    });
+}

package/dist/tools/cron-run.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayCronRuntime } from "../cron/runtime";
+export declare function createCronRunTool(runtime: GatewayCronRuntime): ToolDefinition;

package/dist/tools/cron-run.js

@@ -0,0 +1,20 @@
+import { tool } from "@opencode-ai/plugin";
+export function createCronRunTool(runtime) {
+    return tool({
+        description: "Run one persisted gateway cron job immediately without changing its schedule",
+        args: {
+            id: tool.schema.string().min(1),
+        },
+        async execute(args) {
+            return formatRuntimeReport(await runtime.runNow(args.id));
+        },
+    });
+}
+function formatRuntimeReport(report) {
+    return [
+        `conversation_key=${report.conversationKey}`,
+        `response_text=${report.responseText}`,
+        `delivered=${report.delivered}`,
+        `recorded_at_ms=${report.recordedAtMs}`,
+    ].join("\n");
+}

package/dist/tools/cron-upsert.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayCronRuntime } from "../cron/runtime";
+export declare function createCronUpsertTool(runtime: GatewayCronRuntime): ToolDefinition;

package/dist/tools/cron-upsert.js

@@ -0,0 +1,37 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatUnixMsAsUtc, formatUnixMsInTimeZone } from "./time";
+export function createCronUpsertTool(runtime) {
+    return tool({
+        description: "Create or replace a persisted gateway cron job. The schedule uses cron.timezone or the runtime local time zone.",
+        args: {
+            id: tool.schema.string().min(1),
+            schedule: tool.schema.string().min(1),
+            prompt: tool.schema.string().min(1),
+            enabled: tool.schema.boolean().optional(),
+            delivery_channel: tool.schema.string().optional(),
+            delivery_target: tool.schema.string().optional(),
+            delivery_topic: tool.schema.string().optional(),
+        },
+        async execute(args) {
+            const timeZone = runtime.timeZone();
+            const job = runtime.upsertJob({
+                id: args.id,
+                schedule: args.schedule,
+                prompt: args.prompt,
+                enabled: args.enabled ?? true,
+                deliveryChannel: args.delivery_channel ?? null,
+                deliveryTarget: args.delivery_target ?? null,
+                deliveryTopic: args.delivery_topic ?? null,
+            });
+            return [
+                `id=${job.id}`,
+                `enabled=${job.enabled}`,
+                `schedule=${job.schedule}`,
+                `timezone=${timeZone}`,
+                `next_run_at_ms=${job.nextRunAtMs}`,
+                `next_run_at_local=${formatUnixMsInTimeZone(job.nextRunAtMs, timeZone)}`,
+                `next_run_at_utc=${formatUnixMsAsUtc(job.nextRunAtMs)}`,
+            ].join("\n");
+        },
+    });
+}

package/dist/tools/gateway-dispatch-cron.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayExecutorLike } from "../runtime/executor";
+export declare function createGatewayDispatchCronTool(executor: GatewayExecutorLike): ToolDefinition;

package/dist/tools/gateway-dispatch-cron.js

@@ -0,0 +1,33 @@
+import { tool } from "@opencode-ai/plugin";
+export function createGatewayDispatchCronTool(executor) {
+    return tool({
+        description: "Dispatch one gateway cron-style prompt through the gateway runtime",
+        args: {
+            id: tool.schema.string().min(1),
+            schedule: tool.schema.string().min(1),
+            prompt: tool.schema.string().min(1),
+        },
+        async execute(args) {
+            const report = await executor.dispatchCronJob(toCronJobSpec(args));
+            return formatRuntimeReport(report);
+        },
+    });
+}
+function toCronJobSpec(args) {
+    return {
+        id: args.id,
+        schedule: args.schedule,
+        prompt: args.prompt,
+        deliveryChannel: null,
+        deliveryTarget: null,
+        deliveryTopic: null,
+    };
+}
+function formatRuntimeReport(report) {
+    return [
+        `conversation_key=${report.conversationKey}`,
+        `response_text=${report.responseText}`,
+        `delivered=${report.delivered}`,
+        `recorded_at_ms=${report.recordedAtMs}`,
+    ].join("\n");
+}

package/dist/tools/gateway-status.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayPluginRuntime } from "../gateway";
+export declare function createGatewayStatusTool(runtime: GatewayPluginRuntime): ToolDefinition;