opencode-gateway 0.1.0 → 0.1.1

package/dist/cli/doctor.js

@@ -1,18 +1,20 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { GATEWAY_CONFIG_FILE, OPENCODE_CONFIG_FILE } from "../config/paths";
+import { GATEWAY_CONFIG_FILE, OPENCODE_CONFIG_FILE, resolveGatewayWorkspacePath } from "../config/paths";
 import { parseOpencodeConfig } from "./opencode-config";
 import { pathExists, resolveCliConfigDir } from "./paths";
 export async function runDoctor(options, env) {
     const configDir = resolveCliConfigDir(options, env);
     const opencodeConfigPath = join(configDir, OPENCODE_CONFIG_FILE);
     const gatewayConfigPath = join(configDir, GATEWAY_CONFIG_FILE);
+    const workspaceDirPath = resolveGatewayWorkspacePath(gatewayConfigPath);
     const opencodeStatus = await inspectOpencodeConfig(opencodeConfigPath);
     const gatewayOverride = env.OPENCODE_GATEWAY_CONFIG?.trim() || null;
     console.log("doctor report");
     console.log(`  config dir: ${configDir}`);
     console.log(`  opencode config: ${await describePath(opencodeConfigPath)}`);
     console.log(`  gateway config: ${await describePath(gatewayConfigPath)}`);
+    console.log(`  gateway workspace: ${await describePath(workspaceDirPath)}`);
     console.log(`  gateway config override: ${gatewayOverride ?? "not set"}`);
     console.log(`  plugin configured: ${opencodeStatus.pluginConfigured}`);
     console.log(`  TELEGRAM_BOT_TOKEN: ${env.TELEGRAM_BOT_TOKEN?.trim() ? "set" : "missing"}`);

package/dist/cli/init.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { defaultGatewayStateDbPath, GATEWAY_CONFIG_FILE, OPENCODE_CONFIG_FILE, } from "../config/paths";
+import { defaultGatewayStateDbPath, GATEWAY_CONFIG_FILE, OPENCODE_CONFIG_FILE, resolveGatewayWorkspacePath, } from "../config/paths";
 import { createDefaultOpencodeConfig, ensureGatewayPlugin, parseOpencodeConfig, stringifyOpencodeConfig, } from "./opencode-config";
 import { pathExists, resolveCliConfigDir } from "./paths";
 import { buildGatewayConfigTemplate } from "./templates";
@@ -8,7 +8,9 @@ export async function runInit(options, env) {
     const configDir = resolveCliConfigDir(options, env);
     const opencodeConfigPath = join(configDir, OPENCODE_CONFIG_FILE);
     const gatewayConfigPath = join(configDir, GATEWAY_CONFIG_FILE);
+    const workspaceDirPath = resolveGatewayWorkspacePath(gatewayConfigPath);
     await mkdir(configDir, { recursive: true });
+    await mkdir(workspaceDirPath, { recursive: true });
     let opencodeStatus = "already present";
     if (!(await pathExists(opencodeConfigPath))) {
         await writeFile(opencodeConfigPath, stringifyOpencodeConfig(createDefaultOpencodeConfig(options.managed)));
@@ -32,4 +34,5 @@ export async function runInit(options, env) {
     console.log(`config dir: ${configDir}`);
     console.log(`opencode config: ${opencodeConfigPath} (${opencodeStatus})`);
     console.log(`gateway config: ${gatewayConfigPath} (${gatewayStatus})`);
+    console.log(`gateway workspace: ${workspaceDirPath} (ready)`);
 }

package/dist/cli/paths.js

@@ -1,5 +1,5 @@
-import { access } from "node:fs/promises";
 import { constants } from "node:fs";
+import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import { resolveManagedOpencodeConfigDir, resolveOpencodeConfigDir } from "../config/paths";
 export function resolveCliConfigDir(options, env) {

package/dist/cli.js

@@ -62,9 +62,10 @@ import { join as join2 } from "node:path";
 
 // src/config/paths.ts
 import { homedir } from "node:os";
-import { join, resolve as resolve2 } from "node:path";
+import { dirname, join, resolve as resolve2 } from "node:path";
 var GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
 var OPENCODE_CONFIG_FILE = "opencode.json";
+var GATEWAY_WORKSPACE_DIR = "opencode-gateway-workspace";
 function resolveOpencodeConfigDir(env) {
   const explicit = env.OPENCODE_CONFIG_DIR;
   if (explicit && explicit.trim().length > 0) {
@@ -75,6 +76,9 @@ function resolveOpencodeConfigDir(env) {
 function resolveManagedOpencodeConfigDir(env) {
   return join(resolveConfigHome(env), "opencode-gateway", "opencode");
 }
+function resolveGatewayWorkspacePath(configPath) {
+  return join(dirname(configPath), GATEWAY_WORKSPACE_DIR);
+}
 function defaultGatewayStateDbPath(env) {
   return join(resolveDataHome(env), "opencode-gateway", "state.db");
 }
@@ -153,8 +157,8 @@ function formatError(error) {
 }
 
 // src/cli/paths.ts
-import { access } from "node:fs/promises";
 import { constants } from "node:fs";
+import { access } from "node:fs/promises";
 import { resolve as resolve3 } from "node:path";
 function resolveCliConfigDir(options, env) {
   if (options.configDir !== null) {
@@ -179,12 +183,14 @@ async function runDoctor(options, env) {
   const configDir = resolveCliConfigDir(options, env);
   const opencodeConfigPath = join2(configDir, OPENCODE_CONFIG_FILE);
   const gatewayConfigPath = join2(configDir, GATEWAY_CONFIG_FILE);
+  const workspaceDirPath = resolveGatewayWorkspacePath(gatewayConfigPath);
   const opencodeStatus = await inspectOpencodeConfig(opencodeConfigPath);
   const gatewayOverride = env.OPENCODE_GATEWAY_CONFIG?.trim() || null;
   console.log("doctor report");
   console.log(`  config dir: ${configDir}`);
   console.log(`  opencode config: ${await describePath(opencodeConfigPath)}`);
   console.log(`  gateway config: ${await describePath(gatewayConfigPath)}`);
+  console.log(`  gateway workspace: ${await describePath(workspaceDirPath)}`);
   console.log(`  gateway config override: ${gatewayOverride ?? "not set"}`);
   console.log(`  plugin configured: ${opencodeStatus.pluginConfigured}`);
   console.log(`  TELEGRAM_BOT_TOKEN: ${env.TELEGRAM_BOT_TOKEN?.trim() ? "set" : "missing"}`);
@@ -231,7 +237,7 @@ async function inspectOpencodeConfig(path) {
 
 // src/cli/init.ts
 import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
-import { dirname, join as join3 } from "node:path";
+import { dirname as dirname2, join as join3 } from "node:path";
 
 // src/cli/templates.ts
 function buildGatewayConfigTemplate(stateDbPath) {
@@ -267,7 +273,9 @@ async function runInit(options, env) {
   const configDir = resolveCliConfigDir(options, env);
   const opencodeConfigPath = join3(configDir, OPENCODE_CONFIG_FILE);
   const gatewayConfigPath = join3(configDir, GATEWAY_CONFIG_FILE);
+  const workspaceDirPath = resolveGatewayWorkspacePath(gatewayConfigPath);
   await mkdir(configDir, { recursive: true });
+  await mkdir(workspaceDirPath, { recursive: true });
   let opencodeStatus = "already present";
   if (!await pathExists(opencodeConfigPath)) {
     await writeFile(opencodeConfigPath, stringifyOpencodeConfig(createDefaultOpencodeConfig(options.managed)));
@@ -283,13 +291,14 @@ async function runInit(options, env) {
   }
   let gatewayStatus = "already present";
   if (!await pathExists(gatewayConfigPath)) {
-    await mkdir(dirname(gatewayConfigPath), { recursive: true });
+    await mkdir(dirname2(gatewayConfigPath), { recursive: true });
     await writeFile(gatewayConfigPath, buildGatewayConfigTemplate(defaultGatewayStateDbPath(env)));
     gatewayStatus = "created";
   }
   console.log(`config dir: ${configDir}`);
   console.log(`opencode config: ${opencodeConfigPath} (${opencodeStatus})`);
   console.log(`gateway config: ${gatewayConfigPath} (${gatewayStatus})`);
+  console.log(`gateway workspace: ${workspaceDirPath} (ready)`);
 }
 
 // src/cli.ts

package/dist/config/gateway.d.ts

@@ -15,6 +15,7 @@ export type GatewayConfig = {
     configPath: string;
     stateDbPath: string;
     mediaRootPath: string;
+    workspaceDirPath: string;
     hasLegacyGatewayTimezone: boolean;
     legacyGatewayTimezone: string | null;
     mailbox: GatewayMailboxConfig;

package/dist/config/gateway.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { parseCronConfig } from "./cron";
-import { defaultGatewayStateDbPath, resolveGatewayConfigPath } from "./paths";
+import { defaultGatewayStateDbPath, resolveGatewayConfigPath, resolveGatewayWorkspacePath } from "./paths";
 import { parseTelegramConfig } from "./telegram";
 export async function loadGatewayConfig(env = process.env) {
     const configPath = resolveGatewayConfigPath(env);
@@ -15,6 +15,7 @@ export async function loadGatewayConfig(env = process.env) {
         configPath,
         stateDbPath,
         mediaRootPath: resolveMediaRootPath(stateDbPath),
+        workspaceDirPath: resolveGatewayWorkspacePath(configPath),
         hasLegacyGatewayTimezone: rawConfig?.gateway?.timezone !== undefined,
         legacyGatewayTimezone: readLegacyGatewayTimezone(rawConfig?.gateway?.timezone),
         mailbox: parseMailboxConfig(rawConfig?.gateway?.mailbox),

package/dist/config/paths.d.ts

@@ -1,9 +1,11 @@
 export declare const GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
 export declare const OPENCODE_CONFIG_FILE = "opencode.json";
+export declare const GATEWAY_WORKSPACE_DIR = "opencode-gateway-workspace";
 type EnvSource = Record<string, string | undefined>;
 export declare function resolveGatewayConfigPath(env: EnvSource): string;
 export declare function resolveOpencodeConfigDir(env: EnvSource): string;
 export declare function resolveManagedOpencodeConfigDir(env: EnvSource): string;
+export declare function resolveGatewayWorkspacePath(configPath: string): string;
 export declare function defaultGatewayStateDbPath(env: EnvSource): string;
 export declare function resolveConfigHome(env: EnvSource): string;
 export declare function resolveDataHome(env: EnvSource): string;

package/dist/config/paths.js

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 export const GATEWAY_CONFIG_FILE = "opencode-gateway.toml";
 export const OPENCODE_CONFIG_FILE = "opencode.json";
+export const GATEWAY_WORKSPACE_DIR = "opencode-gateway-workspace";
 export function resolveGatewayConfigPath(env) {
     const explicit = env.OPENCODE_GATEWAY_CONFIG;
     if (explicit && explicit.trim().length > 0) {
@@ -19,6 +20,9 @@ export function resolveOpencodeConfigDir(env) {
 export function resolveManagedOpencodeConfigDir(env) {
     return join(resolveConfigHome(env), "opencode-gateway", "opencode");
 }
+export function resolveGatewayWorkspacePath(configPath) {
+    return join(dirname(configPath), GATEWAY_WORKSPACE_DIR);
+}
 export function defaultGatewayStateDbPath(env) {
     return join(resolveDataHome(env), "opencode-gateway", "state.db");
 }

package/dist/cron/runtime.d.ts

@@ -1,7 +1,7 @@
-import type { BindingLoggerHost, BindingRuntimeReport, GatewayContract } from "../binding";
+import type { BindingDeliveryTarget, BindingLoggerHost, BindingRuntimeReport, GatewayContract } from "../binding";
 import type { CronConfig } from "../config/cron";
 import type { GatewayExecutorLike } from "../runtime/executor";
-import type { CronJobRecord, SqliteStore } from "../store/sqlite";
+import type { CronJobRecord, CronRunRecord, SqliteStore } from "../store/sqlite";
 export type UpsertCronJobInput = {
     id: string;
     schedule: string;
@@ -11,6 +11,21 @@ export type UpsertCronJobInput = {
     deliveryTarget: string | null;
     deliveryTopic: string | null;
 };
+export type ScheduleOnceInput = {
+    id: string;
+    prompt: string;
+    delaySeconds: number | null;
+    runAtMs: number | null;
+    deliveryChannel: string | null;
+    deliveryTarget: string | null;
+    deliveryTopic: string | null;
+};
+export type ScheduleJobState = "scheduled" | "running" | "succeeded" | "failed" | "abandoned" | "canceled";
+export type ScheduleJobStatus = {
+    job: CronJobRecord;
+    state: ScheduleJobState;
+    runs: CronRunRecord[];
+};
 export declare class GatewayCronRuntime {
     private readonly executor;
     private readonly contract;
@@ -18,22 +33,26 @@ export declare class GatewayCronRuntime {
     private readonly logger;
     private readonly config;
     private readonly effectiveTimeZone;
+    private readonly resolveConversationKeyForTarget;
     private readonly runningJobIds;
     private running;
-    constructor(executor: GatewayExecutorLike, contract: GatewayContract, store: SqliteStore, logger: BindingLoggerHost, config: CronConfig, effectiveTimeZone: string);
+    constructor(executor: GatewayExecutorLike, contract: GatewayContract, store: SqliteStore, logger: BindingLoggerHost, config: CronConfig, effectiveTimeZone: string, resolveConversationKeyForTarget: (target: BindingDeliveryTarget) => string);
     isEnabled(): boolean;
     isRunning(): boolean;
     runningJobs(): number;
     timeZone(): string;
     start(): void;
-    listJobs(): CronJobRecord[];
+    listJobs(includeTerminal?: boolean): CronJobRecord[];
+    getJobStatus(id: string, limit?: number): ScheduleJobStatus;
     upsertJob(input: UpsertCronJobInput): CronJobRecord;
-    removeJob(id: string): boolean;
+    scheduleOnce(input: ScheduleOnceInput): CronJobRecord;
+    cancelJob(id: string): boolean;
     runNow(id: string): Promise<BindingRuntimeReport>;
     private runLoop;
     reconcileOnce(nowMs?: number): Promise<void>;
     tickOnce(nowMs?: number): Promise<void>;
     private executeJob;
+    private appendScheduleResultToTarget;
     private requireJob;
     private rebaseJobs;
     private readStoredEffectiveTimeZone;

package/dist/cron/runtime.js

@@ -1,6 +1,7 @@
 import { formatError } from "../utils/error";
 const CRON_EFFECTIVE_TIME_ZONE_KEY = "cron.effective_timezone";
 const LEGACY_CRON_TIME_ZONE = "UTC";
+const MAX_STATUS_RUNS = 20;
 export class GatewayCronRuntime {
     executor;
     contract;
@@ -8,15 +9,17 @@ export class GatewayCronRuntime {
     logger;
     config;
     effectiveTimeZone;
+    resolveConversationKeyForTarget;
     runningJobIds = new Set();
     running = false;
-    constructor(executor, contract, store, logger, config, effectiveTimeZone) {
+    constructor(executor, contract, store, logger, config, effectiveTimeZone, resolveConversationKeyForTarget) {
         this.executor = executor;
         this.contract = contract;
         this.store = store;
         this.logger = logger;
         this.config = config;
         this.effectiveTimeZone = effectiveTimeZone;
+        this.resolveConversationKeyForTarget = resolveConversationKeyForTarget;
     }
     isEnabled() {
         return this.config.enabled;
@@ -39,8 +42,21 @@ export class GatewayCronRuntime {
             this.running = false;
         });
     }
-    listJobs() {
-        return this.store.listCronJobs();
+    listJobs(includeTerminal = false) {
+        const jobs = this.store.listCronJobs();
+        if (includeTerminal) {
+            return jobs;
+        }
+        return jobs.filter((job) => !isTerminalJob(job));
+    }
+    getJobStatus(id, limit = 5) {
+        const job = this.requireJob(normalizeId(id));
+        const runs = this.store.listCronRuns(job.id, clampStatusLimit(limit));
+        return {
+            job,
+            state: deriveJobState(job, runs[0] ?? null),
+            runs,
+        };
     }
     upsertJob(input) {
         const normalized = normalizeUpsertInput(input);
@@ -53,13 +69,31 @@ export class GatewayCronRuntime {
         });
         return this.requireJob(normalized.id);
     }
-    removeJob(id) {
-        return this.store.removeCronJob(normalizeId(id));
+    scheduleOnce(input) {
+        const normalized = normalizeOnceInput(input);
+        const recordedAtMs = Date.now();
+        this.store.upsertCronJob({
+            ...normalized,
+            nextRunAtMs: normalized.runAtMs ?? recordedAtMs,
+            recordedAtMs,
+        });
+        return this.requireJob(normalized.id);
+    }
+    cancelJob(id) {
+        const job = this.store.getCronJob(normalizeId(id));
+        if (job === null || !job.enabled) {
+            return false;
+        }
+        this.store.setCronJobEnabled(job.id, false, Date.now());
+        return true;
     }
     async runNow(id) {
         const job = this.requireJob(normalizeId(id));
+        if (!job.enabled) {
+            throw new Error(`schedule job is not active: ${job.id}`);
+        }
         if (this.runningJobIds.has(job.id)) {
-            throw new Error(`cron job is already running: ${job.id}`);
+            throw new Error(`schedule job is already running: ${job.id}`);
         }
         this.runningJobIds.add(job.id);
         try {
@@ -88,7 +122,7 @@ export class GatewayCronRuntime {
                 ? `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);
+            this.rebaseJobs(this.store.listCronJobs().filter((job) => job.enabled && job.kind === "cron"), nowMs);
         }
         else {
             this.rebaseJobs(this.store.listOverdueCronJobs(nowMs), nowMs);
@@ -108,7 +142,7 @@ export class GatewayCronRuntime {
             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)}`);
+                this.logger.log("error", `schedule job ${job.id} failed: ${formatError(error)}`);
             })
                 .finally(() => {
                 this.runningJobIds.delete(job.id);
@@ -120,26 +154,60 @@ export class GatewayCronRuntime {
     }
     async executeJob(job, scheduledForMs, nextRunBaseMs) {
         const startedAtMs = Date.now();
-        if (nextRunBaseMs !== null) {
+        if (job.kind === "cron" && nextRunBaseMs !== null) {
             const nextRunAtMs = computeNextRunAt(this.contract, job, Math.max(nextRunBaseMs, scheduledForMs), this.effectiveTimeZone);
             this.store.updateCronJobNextRun(job.id, nextRunAtMs, startedAtMs);
         }
+        else if (job.kind === "once") {
+            this.store.setCronJobEnabled(job.id, false, startedAtMs);
+        }
         const runId = this.store.insertCronRun(job.id, scheduledForMs, startedAtMs);
         try {
-            const report = await this.executor.dispatchCronJob(toBindingCronJobSpec(job));
+            const report = await this.executor.dispatchScheduledJob({
+                jobId: job.id,
+                jobKind: job.kind,
+                conversationKey: conversationKeyForJob(job),
+                prompt: job.prompt,
+                replyTarget: toReplyTarget(job),
+            });
             this.store.finishCronRun(runId, "succeeded", Date.now(), report.responseText, null);
+            await this.appendScheduleResultToTarget(job, scheduledForMs, {
+                kind: "success",
+                responseText: report.responseText,
+            });
             return report;
         }
         catch (error) {
             const message = formatError(error);
             this.store.finishCronRun(runId, "failed", Date.now(), null, message);
+            await this.appendScheduleResultToTarget(job, scheduledForMs, {
+                kind: "failure",
+                errorMessage: message,
+            });
             throw error;
         }
     }
+    async appendScheduleResultToTarget(job, scheduledForMs, outcome) {
+        const replyTarget = toReplyTarget(job);
+        if (replyTarget === null) {
+            return;
+        }
+        try {
+            await this.executor.appendContextToConversation({
+                conversationKey: this.resolveConversationKeyForTarget(replyTarget),
+                replyTarget,
+                body: formatScheduleContextNote(job, scheduledForMs, outcome),
+                recordedAtMs: Date.now(),
+            });
+        }
+        catch (error) {
+            this.logger.log("warn", `failed to append schedule result to ${replyTarget.channel}:${replyTarget.target}: ${formatError(error)}`);
+        }
+    }
     requireJob(id) {
         const job = this.store.getCronJob(id);
         if (job === null) {
-            throw new Error(`unknown cron job: ${id}`);
+            throw new Error(`unknown schedule job: ${id}`);
         }
         return job;
     }
@@ -186,7 +254,9 @@ function normalizeUpsertInput(input) {
     }
     return {
         id,
+        kind: "cron",
         schedule,
+        runAtMs: null,
         prompt,
         enabled: input.enabled,
         deliveryChannel,
@@ -196,8 +266,57 @@ function normalizeUpsertInput(input) {
         recordedAtMs: 0,
     };
 }
+function normalizeOnceInput(input) {
+    const id = normalizeId(input.id);
+    const prompt = normalizeRequiredField(input.prompt, "schedule prompt");
+    const deliveryChannel = normalizeOptionalField(input.deliveryChannel);
+    const deliveryTarget = normalizeOptionalField(input.deliveryTarget);
+    const deliveryTopic = normalizeOptionalField(input.deliveryTopic);
+    if ((deliveryChannel === null) !== (deliveryTarget === null)) {
+        throw new Error("schedule delivery_channel and delivery_target must be provided together");
+    }
+    if (deliveryChannel === null && deliveryTopic !== null) {
+        throw new Error("schedule delivery_topic requires delivery_channel and delivery_target");
+    }
+    if (deliveryChannel !== null && deliveryChannel !== "telegram") {
+        throw new Error(`unsupported schedule delivery channel: ${deliveryChannel}`);
+    }
+    const runAtMs = resolveOnceRunAt(input);
+    return {
+        id,
+        kind: "once",
+        schedule: null,
+        runAtMs,
+        prompt,
+        enabled: true,
+        deliveryChannel,
+        deliveryTarget,
+        deliveryTopic,
+        nextRunAtMs: runAtMs,
+        recordedAtMs: 0,
+    };
+}
+function resolveOnceRunAt(input) {
+    if (input.delaySeconds === null && input.runAtMs === null) {
+        throw new Error("schedule_once requires delay_seconds or run_at_ms");
+    }
+    if (input.delaySeconds !== null && input.runAtMs !== null) {
+        throw new Error("schedule_once accepts only one of delay_seconds or run_at_ms");
+    }
+    if (input.runAtMs !== null) {
+        if (!Number.isSafeInteger(input.runAtMs) || input.runAtMs < 0) {
+            throw new Error("schedule run_at_ms must be a non-negative integer");
+        }
+        return input.runAtMs;
+    }
+    const delaySeconds = input.delaySeconds ?? 0;
+    if (!Number.isSafeInteger(delaySeconds) || delaySeconds < 0) {
+        throw new Error("schedule delay_seconds must be a non-negative integer");
+    }
+    return Date.now() + delaySeconds * 1_000;
+}
 function normalizeId(id) {
-    return normalizeRequiredField(id, "cron id");
+    return normalizeRequiredField(id, "schedule id");
 }
 function normalizeRequiredField(value, field) {
     const trimmed = value.trim();
@@ -216,7 +335,7 @@ function normalizeOptionalField(value) {
 function toBindingCronJobSpec(job) {
     return {
         id: job.id,
-        schedule: job.schedule,
+        schedule: normalizeRequiredField(job.schedule ?? "", "cron schedule"),
         prompt: job.prompt,
         deliveryChannel: job.deliveryChannel,
         deliveryTarget: job.deliveryTarget,
@@ -235,3 +354,49 @@ function sleep(durationMs) {
         setTimeout(resolve, durationMs);
     });
 }
+function clampStatusLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        throw new Error("schedule_status limit must be a positive integer");
+    }
+    return Math.min(limit, MAX_STATUS_RUNS);
+}
+function deriveJobState(job, latestRun) {
+    if (latestRun?.status === "running") {
+        return "running";
+    }
+    if (job.enabled) {
+        return "scheduled";
+    }
+    if (latestRun !== null) {
+        return latestRun.status;
+    }
+    return "canceled";
+}
+function isTerminalJob(job) {
+    return !job.enabled;
+}
+function toReplyTarget(job) {
+    if (job.deliveryChannel === null || job.deliveryTarget === null) {
+        return null;
+    }
+    return {
+        channel: job.deliveryChannel,
+        target: job.deliveryTarget,
+        topic: job.deliveryTopic,
+    };
+}
+function conversationKeyForJob(job) {
+    return job.kind === "cron" ? `cron:${job.id}` : `once:${job.id}`;
+}
+function formatScheduleContextNote(job, scheduledForMs, outcome) {
+    const header = [
+        "[Gateway schedule result]",
+        `job_id=${job.id}`,
+        `job_kind=${job.kind}`,
+        `scheduled_for_ms=${scheduledForMs}`,
+    ];
+    if (outcome.kind === "success") {
+        return [...header, "status=succeeded", "", outcome.responseText].join("\n");
+    }
+    return [...header, "status=failed", "", outcome.errorMessage].join("\n");
+}

package/dist/delivery/text.js

@@ -114,7 +114,7 @@ class ProgressiveTextDeliverySession {
         this.telegramSupport.startTyping(this.target);
     }
     async preview(text) {
-        if (this.previewFailed || this.closed) {
+        if (this.previewFailed || this.closed || text.trim().length === 0) {
             return;
         }
         const runPreview = async () => {

package/dist/gateway.js

@@ -1,3 +1,4 @@
+import { mkdir } from "node:fs/promises";
 import { loadGatewayConfig } from "./config/gateway";
 import { GatewayCronRuntime } from "./cron/runtime";
 import { TelegramProgressiveSupport } from "./delivery/telegram";
@@ -13,7 +14,9 @@ import { createQuestionClient } from "./questions/client";
 import { GatewayQuestionRuntime } from "./questions/runtime";
 import { GatewayExecutor } from "./runtime/executor";
 import { GatewayMailboxRuntime } from "./runtime/mailbox";
+import { getOrCreateRuntimeSingleton } from "./runtime/runtime-singleton";
 import { GatewaySessionContext } from "./session/context";
+import { resolveConversationKeyForTarget } from "./session/conversation-key";
 import { ChannelSessionSwitcher } from "./session/switcher";
 import { openSqliteStore } from "./store/sqlite";
 import { TelegramBotClient } from "./telegram/client";
@@ -56,41 +59,44 @@ export class GatewayPluginRuntime {
 }
 export async function createGatewayRuntime(module, input) {
     const config = await loadGatewayConfig();
-    const logger = new ConsoleLoggerHost();
-    if (config.hasLegacyGatewayTimezone) {
-        const suffix = config.legacyGatewayTimezone === null ? "" : ` (${config.legacyGatewayTimezone})`;
-        logger.log("warn", `gateway.timezone${suffix} is ignored; use cron.timezone instead`);
-    }
-    const effectiveCronTimeZone = resolveEffectiveCronTimeZone(module, config);
-    const store = await openSqliteStore(config.stateDbPath);
-    const sessionContext = new GatewaySessionContext(store);
-    const telegramClient = config.telegram.enabled ? new TelegramBotClient(config.telegram.botToken) : null;
-    const telegramMediaStore = config.telegram.enabled && telegramClient !== null
-        ? new TelegramInboundMediaStore(telegramClient, config.mediaRootPath)
-        : null;
-    const mailboxRouter = new GatewayMailboxRouter(config.mailbox.routes);
-    const opencodeEvents = new OpencodeEventHub();
-    const opencode = new OpencodeSdkAdapter(input.client, input.directory);
-    const questionClient = createQuestionClient(input.client, input.serverUrl, input.directory);
-    const transport = new GatewayTransportHost(telegramClient, store);
-    const files = new ChannelFileSender(telegramClient);
-    const channelSessions = new ChannelSessionSwitcher(store, sessionContext, mailboxRouter, module, opencode, config.telegram.enabled);
-    const questions = new GatewayQuestionRuntime(questionClient, input.directory, store, sessionContext, transport, telegramClient, logger);
-    const progressiveSupport = new TelegramProgressiveSupport(telegramClient, store, logger);
-    const delivery = new GatewayTextDelivery(transport, store, progressiveSupport);
-    const executor = new GatewayExecutor(module, store, opencode, opencodeEvents, delivery, logger);
-    const mailbox = new GatewayMailboxRuntime(executor, store, logger, config.mailbox, questions);
-    const cron = new GatewayCronRuntime(executor, module, store, logger, config.cron, effectiveCronTimeZone);
-    const eventStream = new OpencodeEventStream(input.client, input.directory, opencodeEvents, [questions], logger);
-    const telegramPolling = config.telegram.enabled && telegramClient !== null && telegramMediaStore !== null
-        ? new TelegramPollingService(telegramClient, mailbox, store, logger, config.telegram, mailboxRouter, telegramMediaStore, questions)
-        : null;
-    const telegram = new GatewayTelegramRuntime(telegramClient, delivery, store, logger, config.telegram, telegramPolling, eventStream);
-    eventStream.start();
-    cron.start();
-    mailbox.start();
-    telegram.start();
-    return new GatewayPluginRuntime(module, executor, cron, telegram, files, channelSessions, sessionContext);
+    return await getOrCreateRuntimeSingleton(config.configPath, async () => {
+        await mkdir(config.workspaceDirPath, { recursive: true });
+        const logger = new ConsoleLoggerHost();
+        if (config.hasLegacyGatewayTimezone) {
+            const suffix = config.legacyGatewayTimezone === null ? "" : ` (${config.legacyGatewayTimezone})`;
+            logger.log("warn", `gateway.timezone${suffix} is ignored; use cron.timezone instead`);
+        }
+        const effectiveCronTimeZone = resolveEffectiveCronTimeZone(module, config);
+        const store = await openSqliteStore(config.stateDbPath);
+        const sessionContext = new GatewaySessionContext(store);
+        const telegramClient = config.telegram.enabled ? new TelegramBotClient(config.telegram.botToken) : null;
+        const telegramMediaStore = config.telegram.enabled && telegramClient !== null
+            ? new TelegramInboundMediaStore(telegramClient, config.mediaRootPath)
+            : null;
+        const mailboxRouter = new GatewayMailboxRouter(config.mailbox.routes);
+        const opencodeEvents = new OpencodeEventHub();
+        const opencode = new OpencodeSdkAdapter(input.client, config.workspaceDirPath);
+        const questionClient = createQuestionClient(input.client, input.serverUrl, config.workspaceDirPath);
+        const transport = new GatewayTransportHost(telegramClient, store);
+        const files = new ChannelFileSender(telegramClient);
+        const channelSessions = new ChannelSessionSwitcher(store, sessionContext, mailboxRouter, module, opencode, config.telegram.enabled);
+        const questions = new GatewayQuestionRuntime(questionClient, config.workspaceDirPath, store, sessionContext, transport, telegramClient, logger);
+        const progressiveSupport = new TelegramProgressiveSupport(telegramClient, store, logger);
+        const delivery = new GatewayTextDelivery(transport, store, progressiveSupport);
+        const executor = new GatewayExecutor(module, store, opencode, opencodeEvents, delivery, logger);
+        const mailbox = new GatewayMailboxRuntime(executor, store, logger, config.mailbox, questions);
+        const cron = new GatewayCronRuntime(executor, module, store, logger, config.cron, effectiveCronTimeZone, (target) => resolveConversationKeyForTarget(target, mailboxRouter, module));
+        const eventStream = new OpencodeEventStream(input.client, config.workspaceDirPath, opencodeEvents, [questions], logger);
+        const telegramPolling = config.telegram.enabled && telegramClient !== null && telegramMediaStore !== null
+            ? new TelegramPollingService(telegramClient, mailbox, store, logger, config.telegram, mailboxRouter, telegramMediaStore, questions)
+            : null;
+        const telegram = new GatewayTelegramRuntime(telegramClient, delivery, store, logger, config.telegram, telegramPolling, eventStream);
+        eventStream.start();
+        cron.start();
+        mailbox.start();
+        telegram.start();
+        return new GatewayPluginRuntime(module, executor, cron, telegram, files, channelSessions, sessionContext);
+    });
 }
 function resolveEffectiveCronTimeZone(module, config) {
     const candidate = config.cron.timezone ?? resolveRuntimeLocalTimeZone();