opencode-gateway 0.1.0

package/dist/cron/runtime.d.ts

@@ -0,0 +1,40 @@
+import type { BindingLoggerHost, BindingRuntimeReport, GatewayContract } from "../binding";
+import type { CronConfig } from "../config/cron";
+import type { GatewayExecutorLike } from "../runtime/executor";
+import type { CronJobRecord, SqliteStore } from "../store/sqlite";
+export type UpsertCronJobInput = {
+    id: string;
+    schedule: string;
+    prompt: string;
+    enabled: boolean;
+    deliveryChannel: string | null;
+    deliveryTarget: string | null;
+    deliveryTopic: string | null;
+};
+export declare class GatewayCronRuntime {
+    private readonly executor;
+    private readonly contract;
+    private readonly store;
+    private readonly logger;
+    private readonly config;
+    private readonly effectiveTimeZone;
+    private readonly runningJobIds;
+    private running;
+    constructor(executor: GatewayExecutorLike, contract: GatewayContract, store: SqliteStore, logger: BindingLoggerHost, config: CronConfig, effectiveTimeZone: string);
+    isEnabled(): boolean;
+    isRunning(): boolean;
+    runningJobs(): number;
+    timeZone(): string;
+    start(): void;
+    listJobs(): CronJobRecord[];
+    upsertJob(input: UpsertCronJobInput): CronJobRecord;
+    removeJob(id: string): boolean;
+    runNow(id: string): Promise<BindingRuntimeReport>;
+    private runLoop;
+    reconcileOnce(nowMs?: number): Promise<void>;
+    tickOnce(nowMs?: number): Promise<void>;
+    private executeJob;
+    private requireJob;
+    private rebaseJobs;
+    private readStoredEffectiveTimeZone;
+}

package/dist/cron/runtime.js

@@ -0,0 +1,237 @@
+import { formatError } from "../utils/error";
+const CRON_EFFECTIVE_TIME_ZONE_KEY = "cron.effective_timezone";
+const LEGACY_CRON_TIME_ZONE = "UTC";
+export class GatewayCronRuntime {
+    executor;
+    contract;
+    store;
+    logger;
+    config;
+    effectiveTimeZone;
+    runningJobIds = new Set();
+    running = false;
+    constructor(executor, contract, store, logger, config, effectiveTimeZone) {
+        this.executor = executor;
+        this.contract = contract;
+        this.store = store;
+        this.logger = logger;
+        this.config = config;
+        this.effectiveTimeZone = effectiveTimeZone;
+    }
+    isEnabled() {
+        return this.config.enabled;
+    }
+    isRunning() {
+        return this.running;
+    }
+    runningJobs() {
+        return this.runningJobIds.size;
+    }
+    timeZone() {
+        return this.effectiveTimeZone;
+    }
+    start() {
+        if (!this.config.enabled || this.running) {
+            return;
+        }
+        this.running = true;
+        void this.runLoop().finally(() => {
+            this.running = false;
+        });
+    }
+    listJobs() {
+        return this.store.listCronJobs();
+    }
+    upsertJob(input) {
+        const normalized = normalizeUpsertInput(input);
+        const recordedAtMs = Date.now();
+        const nextRunAtMs = computeNextRunAt(this.contract, normalized, recordedAtMs, this.effectiveTimeZone);
+        this.store.upsertCronJob({
+            ...normalized,
+            nextRunAtMs,
+            recordedAtMs,
+        });
+        return this.requireJob(normalized.id);
+    }
+    removeJob(id) {
+        return this.store.removeCronJob(normalizeId(id));
+    }
+    async runNow(id) {
+        const job = this.requireJob(normalizeId(id));
+        if (this.runningJobIds.has(job.id)) {
+            throw new Error(`cron job is already running: ${job.id}`);
+        }
+        this.runningJobIds.add(job.id);
+        try {
+            return await this.executeJob(job, Date.now(), null);
+        }
+        finally {
+            this.runningJobIds.delete(job.id);
+        }
+    }
+    async runLoop() {
+        await this.reconcileOnce();
+        for (;;) {
+            await this.tickOnce();
+            await sleep(this.config.tickSeconds * 1_000);
+        }
+    }
+    async reconcileOnce(nowMs = Date.now()) {
+        const abandoned = this.store.abandonRunningCronRuns(nowMs);
+        if (abandoned > 0) {
+            this.logger.log("warn", `abandoned ${abandoned} stale cron runs on startup`);
+        }
+        const storedTimeZone = this.readStoredEffectiveTimeZone();
+        const previousTimeZone = storedTimeZone ?? LEGACY_CRON_TIME_ZONE;
+        if (previousTimeZone !== this.effectiveTimeZone) {
+            const message = storedTimeZone === null
+                ? `rebasing enabled cron jobs from legacy ${LEGACY_CRON_TIME_ZONE} semantics to ${this.effectiveTimeZone}`
+                : `cron time zone changed from ${previousTimeZone} to ${this.effectiveTimeZone}; rebasing enabled jobs`;
+            this.logger.log("warn", message);
+            this.rebaseJobs(this.store.listCronJobs().filter((job) => job.enabled), nowMs);
+        }
+        else {
+            this.rebaseJobs(this.store.listOverdueCronJobs(nowMs), nowMs);
+        }
+        this.store.putStateValue(CRON_EFFECTIVE_TIME_ZONE_KEY, this.effectiveTimeZone, nowMs);
+    }
+    async tickOnce(nowMs = Date.now()) {
+        const capacity = this.config.maxConcurrentRuns - this.runningJobIds.size;
+        if (capacity <= 0) {
+            return;
+        }
+        const dueJobs = this.store.listDueCronJobs(nowMs, capacity);
+        for (const job of dueJobs) {
+            if (this.runningJobIds.has(job.id)) {
+                continue;
+            }
+            this.runningJobIds.add(job.id);
+            void this.executeJob(job, job.nextRunAtMs, nowMs)
+                .catch((error) => {
+                this.logger.log("error", `cron job ${job.id} failed: ${formatError(error)}`);
+            })
+                .finally(() => {
+                this.runningJobIds.delete(job.id);
+            });
+            if (this.runningJobIds.size >= this.config.maxConcurrentRuns) {
+                return;
+            }
+        }
+    }
+    async executeJob(job, scheduledForMs, nextRunBaseMs) {
+        const startedAtMs = Date.now();
+        if (nextRunBaseMs !== null) {
+            const nextRunAtMs = computeNextRunAt(this.contract, job, Math.max(nextRunBaseMs, scheduledForMs), this.effectiveTimeZone);
+            this.store.updateCronJobNextRun(job.id, nextRunAtMs, startedAtMs);
+        }
+        const runId = this.store.insertCronRun(job.id, scheduledForMs, startedAtMs);
+        try {
+            const report = await this.executor.dispatchCronJob(toBindingCronJobSpec(job));
+            this.store.finishCronRun(runId, "succeeded", Date.now(), report.responseText, null);
+            return report;
+        }
+        catch (error) {
+            const message = formatError(error);
+            this.store.finishCronRun(runId, "failed", Date.now(), null, message);
+            throw error;
+        }
+    }
+    requireJob(id) {
+        const job = this.store.getCronJob(id);
+        if (job === null) {
+            throw new Error(`unknown cron job: ${id}`);
+        }
+        return job;
+    }
+    rebaseJobs(jobs, nowMs) {
+        for (const job of jobs) {
+            try {
+                const nextRunAtMs = computeNextRunAt(this.contract, job, nowMs, this.effectiveTimeZone);
+                this.store.updateCronJobNextRun(job.id, nextRunAtMs, nowMs);
+            }
+            catch (error) {
+                this.logger.log("error", `failed to rebase cron job ${job.id}: ${formatError(error)}`);
+            }
+        }
+    }
+    readStoredEffectiveTimeZone() {
+        const stored = this.store.getStateValue(CRON_EFFECTIVE_TIME_ZONE_KEY);
+        if (stored === null) {
+            return null;
+        }
+        try {
+            return this.contract.normalizeCronTimeZone(stored);
+        }
+        catch (error) {
+            this.logger.log("warn", `stored cron time zone is invalid (${stored}); treating as legacy ${LEGACY_CRON_TIME_ZONE}: ${formatError(error)}`);
+            return null;
+        }
+    }
+}
+function normalizeUpsertInput(input) {
+    const id = normalizeId(input.id);
+    const schedule = normalizeRequiredField(input.schedule, "cron schedule");
+    const prompt = normalizeRequiredField(input.prompt, "cron prompt");
+    const deliveryChannel = normalizeOptionalField(input.deliveryChannel);
+    const deliveryTarget = normalizeOptionalField(input.deliveryTarget);
+    const deliveryTopic = normalizeOptionalField(input.deliveryTopic);
+    if ((deliveryChannel === null) !== (deliveryTarget === null)) {
+        throw new Error("cron delivery_channel and delivery_target must be provided together");
+    }
+    if (deliveryChannel === null && deliveryTopic !== null) {
+        throw new Error("cron delivery_topic requires delivery_channel and delivery_target");
+    }
+    if (deliveryChannel !== null && deliveryChannel !== "telegram") {
+        throw new Error(`unsupported cron delivery channel: ${deliveryChannel}`);
+    }
+    return {
+        id,
+        schedule,
+        prompt,
+        enabled: input.enabled,
+        deliveryChannel,
+        deliveryTarget,
+        deliveryTopic,
+        nextRunAtMs: 0,
+        recordedAtMs: 0,
+    };
+}
+function normalizeId(id) {
+    return normalizeRequiredField(id, "cron id");
+}
+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 toBindingCronJobSpec(job) {
+    return {
+        id: job.id,
+        schedule: job.schedule,
+        prompt: job.prompt,
+        deliveryChannel: job.deliveryChannel,
+        deliveryTarget: job.deliveryTarget,
+        deliveryTopic: job.deliveryTopic,
+    };
+}
+function computeNextRunAt(contract, job, afterMs, timeZone) {
+    const nextRunAt = contract.nextCronRunAt(toBindingCronJobSpec(job), afterMs, timeZone);
+    if (!Number.isSafeInteger(nextRunAt) || nextRunAt < 0) {
+        throw new Error(`next cron run at is out of range for JavaScript: ${nextRunAt}`);
+    }
+    return nextRunAt;
+}
+function sleep(durationMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+}

package/dist/delivery/telegram.d.ts

@@ -0,0 +1,16 @@
+import type { BindingDeliveryTarget, BindingLoggerHost } from "../binding";
+import type { SqliteStore } from "../store/sqlite";
+import type { TelegramDeliveryClientLike } from "../telegram/client";
+export type DeliveryModePreference = "auto" | "oneshot" | "stream";
+export type ResolvedDeliveryMode = "oneshot" | "progressive";
+export declare class TelegramProgressiveSupport {
+    private readonly client;
+    private readonly store;
+    private readonly logger;
+    constructor(client: TelegramDeliveryClientLike | null, store: SqliteStore, logger: BindingLoggerHost);
+    resolveMode(target: BindingDeliveryTarget, preference: DeliveryModePreference): Promise<ResolvedDeliveryMode>;
+    sendDraft(target: BindingDeliveryTarget, draftId: number, text: string): Promise<void>;
+    startTyping(target: BindingDeliveryTarget): void;
+    private isPrivateChat;
+}
+export declare function createDraftId(): number;

package/dist/delivery/telegram.js

@@ -0,0 +1,75 @@
+import { readTelegramChatType, recordTelegramChatType, recordTelegramDraftFailure, recordTelegramDraftSuccess, recordTelegramStreamFallback, } from "../telegram/state";
+import { formatError } from "../utils/error";
+export class TelegramProgressiveSupport {
+    client;
+    store;
+    logger;
+    constructor(client, store, logger) {
+        this.client = client;
+        this.store = store;
+        this.logger = logger;
+    }
+    async resolveMode(target, preference) {
+        if (target.channel !== "telegram" || preference === "oneshot") {
+            return "oneshot";
+        }
+        const isPrivateChat = await this.isPrivateChat(target.target);
+        if (preference === "stream") {
+            if (!isPrivateChat) {
+                throw new Error("telegram draft stream is only supported for private chats");
+            }
+            return "progressive";
+        }
+        if (!isPrivateChat) {
+            recordTelegramStreamFallback(this.store, "non_private_chat", Date.now());
+            return "oneshot";
+        }
+        return "progressive";
+    }
+    async sendDraft(target, draftId, text) {
+        if (this.client === null) {
+            throw new Error("telegram transport is not configured");
+        }
+        try {
+            await this.client.sendMessageDraft(target.target, draftId, text, target.topic);
+            recordTelegramDraftSuccess(this.store, Date.now());
+        }
+        catch (error) {
+            const message = formatError(error);
+            recordTelegramDraftFailure(this.store, message, Date.now());
+            recordTelegramStreamFallback(this.store, "draft_send_failed", Date.now());
+            this.logger.log("warn", `telegram draft send failed: ${message}`);
+            throw error;
+        }
+    }
+    startTyping(target) {
+        if (this.client === null) {
+            return;
+        }
+        void this.client.sendChatAction(target.target, "typing", target.topic).catch(() => {
+            // Typing hints are best-effort only.
+        });
+    }
+    async isPrivateChat(chatId) {
+        const cachedChatType = readTelegramChatType(this.store, chatId);
+        if (cachedChatType !== null) {
+            return cachedChatType === "private";
+        }
+        if (this.client === null) {
+            return false;
+        }
+        try {
+            const chat = await this.client.getChat(chatId);
+            recordTelegramChatType(this.store, chatId, chat.type, Date.now());
+            return chat.type === "private";
+        }
+        catch (error) {
+            this.logger.log("warn", `failed to resolve Telegram chat type for ${chatId}: ${formatError(error)}`);
+            return false;
+        }
+    }
+}
+export function createDraftId() {
+    const draftId = crypto.getRandomValues(new Uint32Array(1))[0];
+    return draftId === 0 ? 1 : draftId;
+}

package/dist/delivery/text.d.ts

@@ -0,0 +1,21 @@
+import type { BindingDeliveryTarget } from "../binding";
+import type { GatewayTransportHost } from "../host/transport";
+import type { SqliteStore } from "../store/sqlite";
+import { type DeliveryModePreference, type TelegramProgressiveSupport } from "./telegram";
+export type TextDeliverySession = {
+    mode: "oneshot" | "progressive";
+    preview(text: string): Promise<void>;
+    finish(finalText: string | null): Promise<boolean>;
+};
+export declare class GatewayTextDelivery {
+    private readonly transport;
+    private readonly store;
+    private readonly telegramSupport;
+    constructor(transport: GatewayTransportHost, store: SqliteStore, telegramSupport: TelegramProgressiveSupport);
+    open(target: BindingDeliveryTarget, preference: DeliveryModePreference): Promise<TextDeliverySession>;
+    openMany(targets: BindingDeliveryTarget[], preference: DeliveryModePreference): Promise<TextDeliverySession[]>;
+    sendTest(target: BindingDeliveryTarget, text: string, preference: DeliveryModePreference): Promise<{
+        delivered: boolean;
+        mode: "oneshot" | "progressive";
+    }>;
+}

package/dist/delivery/text.js

@@ -0,0 +1,175 @@
+import { recordTelegramPreviewEmit, recordTelegramStreamFallback } from "../telegram/state";
+import { createDraftId } from "./telegram";
+export class GatewayTextDelivery {
+    transport;
+    store;
+    telegramSupport;
+    constructor(transport, store, telegramSupport) {
+        this.transport = transport;
+        this.store = store;
+        this.telegramSupport = telegramSupport;
+    }
+    async open(target, preference) {
+        const [session] = await this.openMany([target], preference);
+        return session;
+    }
+    async openMany(targets, preference) {
+        const uniqueTargets = dedupeTargets(targets);
+        if (uniqueTargets.length === 0) {
+            return [new NoopTextDeliverySession()];
+        }
+        const sessions = await Promise.all(uniqueTargets.map(async (target) => {
+            const mode = await this.telegramSupport.resolveMode(target, preference);
+            if (mode === "progressive") {
+                const session = new ProgressiveTextDeliverySession(target, this.transport, this.telegramSupport, this.store);
+                session.start();
+                return session;
+            }
+            return new OneshotTextDeliverySession(target, this.transport);
+        }));
+        if (sessions.length === 1) {
+            return sessions;
+        }
+        return [new FanoutTextDeliverySession(sessions)];
+    }
+    async sendTest(target, text, preference) {
+        const session = await this.open(target, preference);
+        if (session.mode === "progressive") {
+            await session.preview(text.slice(0, Math.max(1, Math.ceil(text.length / 2))));
+        }
+        return {
+            delivered: await session.finish(text),
+            mode: session.mode,
+        };
+    }
+}
+class NoopTextDeliverySession {
+    mode = "oneshot";
+    async preview(_text) { }
+    async finish(_finalText) {
+        return false;
+    }
+}
+class FanoutTextDeliverySession {
+    sessions;
+    mode;
+    constructor(sessions) {
+        this.sessions = sessions;
+        this.mode = sessions.some((session) => session.mode === "progressive") ? "progressive" : "oneshot";
+    }
+    async preview(text) {
+        await Promise.all(this.sessions.map((session) => session.preview(text)));
+    }
+    async finish(finalText) {
+        const results = await Promise.allSettled(this.sessions.map((session) => session.finish(finalText)));
+        const firstFailure = results.find((result) => result.status === "rejected");
+        if (firstFailure?.status === "rejected") {
+            throw firstFailure.reason;
+        }
+        return results.some((result) => result.status === "fulfilled" && result.value);
+    }
+}
+class OneshotTextDeliverySession {
+    target;
+    transport;
+    mode = "oneshot";
+    constructor(target, transport) {
+        this.target = target;
+        this.transport = transport;
+    }
+    async preview(_text) { }
+    async finish(finalText) {
+        if (finalText === null || finalText.trim().length === 0) {
+            return false;
+        }
+        const ack = await this.transport.sendMessage({
+            deliveryTarget: this.target,
+            body: finalText,
+        });
+        if (ack.errorMessage !== null) {
+            throw new Error(ack.errorMessage);
+        }
+        return true;
+    }
+}
+class ProgressiveTextDeliverySession {
+    target;
+    transport;
+    telegramSupport;
+    store;
+    mode = "progressive";
+    previewFailed = false;
+    previewDelivered = false;
+    closed = false;
+    pendingPreviewCount = 0;
+    pendingPreview = Promise.resolve();
+    draftId = createDraftId();
+    constructor(target, transport, telegramSupport, store) {
+        this.target = target;
+        this.transport = transport;
+        this.telegramSupport = telegramSupport;
+        this.store = store;
+    }
+    start() {
+        this.telegramSupport.startTyping(this.target);
+    }
+    async preview(text) {
+        if (this.previewFailed || this.closed) {
+            return;
+        }
+        const runPreview = async () => {
+            try {
+                if (this.previewFailed || this.closed) {
+                    return;
+                }
+                try {
+                    recordTelegramPreviewEmit(this.store, Date.now());
+                    await this.telegramSupport.sendDraft(this.target, this.draftId, text);
+                    this.previewDelivered = true;
+                }
+                catch {
+                    this.previewFailed = true;
+                }
+            }
+            finally {
+                this.pendingPreviewCount = Math.max(0, this.pendingPreviewCount - 1);
+            }
+        };
+        this.pendingPreviewCount += 1;
+        this.pendingPreview = this.pendingPreview.then(runPreview, runPreview);
+        await this.pendingPreview;
+    }
+    async finish(finalText) {
+        this.closed = true;
+        if (this.pendingPreviewCount > 0) {
+            await this.pendingPreview;
+        }
+        if (finalText === null || finalText.trim().length === 0) {
+            return false;
+        }
+        if (!this.previewDelivered && !this.previewFailed) {
+            recordTelegramStreamFallback(this.store, "preview_not_established", Date.now());
+        }
+        const ack = await this.transport.sendMessage({
+            deliveryTarget: this.target,
+            body: finalText,
+        });
+        if (ack.errorMessage !== null) {
+            throw new Error(ack.errorMessage);
+        }
+        return true;
+    }
+}
+function dedupeTargets(targets) {
+    const seen = new Set();
+    const unique = [];
+    for (const target of targets) {
+        const key = `${target.channel}:${target.target}:${target.topic ?? ""}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(target);
+    }
+    return unique;
+}

package/dist/gateway.d.ts

@@ -0,0 +1,33 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { GatewayBindingModule, GatewayContract } from "./binding";
+import { GatewayCronRuntime } from "./cron/runtime";
+import { ChannelFileSender } from "./host/file-sender";
+import { GatewayExecutor } from "./runtime/executor";
+import { GatewaySessionContext } from "./session/context";
+import { ChannelSessionSwitcher } from "./session/switcher";
+import { GatewayTelegramRuntime } from "./telegram/runtime";
+export type GatewayPluginStatus = {
+    runtimeMode: string;
+    supportsTelegram: boolean;
+    supportsCron: boolean;
+    hasWebUi: boolean;
+    cronTimezone: string;
+    cronEnabled: boolean;
+    cronPolling: boolean;
+    cronRunningJobs: number;
+    telegramEnabled: boolean;
+    telegramPolling: boolean;
+    telegramAllowlistMode: "disabled" | "explicit";
+};
+export declare class GatewayPluginRuntime {
+    readonly contract: GatewayContract;
+    readonly executor: GatewayExecutor;
+    readonly cron: GatewayCronRuntime;
+    readonly telegram: GatewayTelegramRuntime;
+    readonly files: ChannelFileSender;
+    readonly channelSessions: ChannelSessionSwitcher;
+    readonly sessionContext: GatewaySessionContext;
+    constructor(contract: GatewayContract, executor: GatewayExecutor, cron: GatewayCronRuntime, telegram: GatewayTelegramRuntime, files: ChannelFileSender, channelSessions: ChannelSessionSwitcher, sessionContext: GatewaySessionContext);
+    status(): GatewayPluginStatus;
+}
+export declare function createGatewayRuntime(module: GatewayBindingModule, input: PluginInput): Promise<GatewayPluginRuntime>;