opencode-gateway 0.1.0 → 0.1.1

package/dist/index.js

@@ -2,12 +2,14 @@ import { loadGatewayBindingModule } from "./binding";
 import { createGatewayRuntime } from "./gateway";
 import { createChannelNewSessionTool } from "./tools/channel-new-session";
 import { createChannelSendFileTool } from "./tools/channel-send-file";
-import { createCronListTool } from "./tools/cron-list";
-import { createCronRemoveTool } from "./tools/cron-remove";
 import { createCronRunTool } from "./tools/cron-run";
 import { createCronUpsertTool } from "./tools/cron-upsert";
 import { createGatewayDispatchCronTool } from "./tools/gateway-dispatch-cron";
 import { createGatewayStatusTool } from "./tools/gateway-status";
+import { createScheduleCancelTool } from "./tools/schedule-cancel";
+import { createScheduleListTool } from "./tools/schedule-list";
+import { createScheduleOnceTool } from "./tools/schedule-once";
+import { createScheduleStatusTool } from "./tools/schedule-status";
 import { createTelegramSendTestTool } from "./tools/telegram-send-test";
 import { createTelegramStatusTool } from "./tools/telegram-status";
 /**
@@ -18,12 +20,14 @@ export const OpencodeGatewayPlugin = async (input) => {
     const gatewayModule = await loadGatewayBindingModule();
     const runtime = await createGatewayRuntime(gatewayModule, input);
     const tools = {
-        cron_list: createCronListTool(runtime.cron),
-        cron_remove: createCronRemoveTool(runtime.cron),
         cron_run: createCronRunTool(runtime.cron),
-        cron_upsert: createCronUpsertTool(runtime.cron),
+        cron_upsert: createCronUpsertTool(runtime.cron, runtime.sessionContext),
         gateway_status: createGatewayStatusTool(runtime),
         gateway_dispatch_cron: createGatewayDispatchCronTool(runtime.executor),
+        schedule_cancel: createScheduleCancelTool(runtime.cron),
+        schedule_list: createScheduleListTool(runtime.cron),
+        schedule_once: createScheduleOnceTool(runtime.cron, runtime.sessionContext),
+        schedule_status: createScheduleStatusTool(runtime.cron),
     };
     if (runtime.files.hasEnabledChannel()) {
         tools.channel_send_file = createChannelSendFileTool(runtime.files, runtime.sessionContext);

package/dist/opencode/adapter.d.ts

@@ -6,6 +6,8 @@ export declare class OpencodeSdkAdapter {
     private readonly directory;
     constructor(client: OpencodeClient, directory: string);
     createFreshSession(title: string): Promise<string>;
+    isSessionBusy(sessionId: string): Promise<boolean>;
+    abortSession(sessionId: string): Promise<void>;
     execute(command: BindingOpencodeCommand): Promise<BindingOpencodeCommandResult>;
     private lookupSession;
     private createSession;

package/dist/opencode/adapter.js

@@ -18,6 +18,31 @@ export class OpencodeSdkAdapter {
         });
         return unwrapData(session).id;
     }
+    async isSessionBusy(sessionId) {
+        const statuses = await this.client.session.status({
+            query: { directory: this.directory },
+            responseStyle: "data",
+            throwOnError: true,
+        });
+        const current = unwrapData(statuses)[sessionId];
+        return current?.type === "busy";
+    }
+    async abortSession(sessionId) {
+        try {
+            await this.client.session.abort({
+                path: { id: sessionId },
+                query: { directory: this.directory },
+                responseStyle: "data",
+                throwOnError: true,
+            });
+        }
+        catch (error) {
+            if (isMissingSessionError(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
     async execute(command) {
         try {
             switch (command.kind) {
@@ -125,6 +150,7 @@ export class OpencodeSdkAdapter {
     }
     async awaitPromptResponse(command) {
         const deadline = Date.now() + PROMPT_RESPONSE_TIMEOUT_MS;
+        let stableCandidateKey = null;
         for (;;) {
             const messages = await this.client.session.messages({
                 path: { id: command.sessionId },
@@ -137,12 +163,19 @@ export class OpencodeSdkAdapter {
             });
             const response = selectAssistantResponse(unwrapData(messages), command.messageId);
             if (response !== null) {
-                return {
-                    kind: "awaitPromptResponse",
-                    sessionId: command.sessionId,
-                    messageId: response.info.id,
-                    parts: response.parts.flatMap(toBindingMessagePart),
-                };
+                const candidateKey = createAssistantCandidateKey(response);
+                if (stableCandidateKey === candidateKey) {
+                    return {
+                        kind: "awaitPromptResponse",
+                        sessionId: command.sessionId,
+                        messageId: response.info.id,
+                        parts: response.parts.flatMap(toBindingMessagePart),
+                    };
+                }
+                stableCandidateKey = candidateKey;
+            }
+            else {
+                stableCandidateKey = null;
             }
             if (Date.now() >= deadline) {
                 throw new Error(`assistant message for prompt ${command.messageId} is unavailable after prompt completion`);
@@ -221,6 +254,19 @@ function selectAssistantResponse(messages, userMessageId) {
     }
     return null;
 }
+function createAssistantCandidateKey(message) {
+    return JSON.stringify({
+        messageId: message.info.id,
+        finish: message.info.finish ?? null,
+        hasError: message.info.error !== undefined,
+        parts: message.parts.map((part) => ({
+            id: part.id ?? null,
+            type: part.type,
+            text: typeof part.text === "string" ? part.text : null,
+            ignored: part.ignored === true,
+        })),
+    });
+}
 function isAssistantChildMessage(userMessageId) {
     return (message) => message.info?.role === "assistant" && message.info.parentID === userMessageId;
 }
@@ -239,7 +285,10 @@ function toBindingMessagePart(part) {
     ];
 }
 function hasVisibleText(message) {
-    return message.parts.some((part) => part.type === "text" && part.ignored !== true && typeof part.text === "string" && part.text.length > 0);
+    return message.parts.some((part) => part.type === "text" &&
+        part.ignored !== true &&
+        typeof part.text === "string" &&
+        part.text.trim().length > 0);
 }
 function toBindingMessage(message) {
     if (typeof message.info?.id !== "string" ||

package/dist/runtime/conversation-coordinator.d.ts

@@ -0,0 +1,4 @@
+export declare class ConversationCoordinator {
+    private readonly tails;
+    runExclusive<T>(conversationKey: string, operation: () => Promise<T>): Promise<T>;
+}

package/dist/runtime/conversation-coordinator.js

@@ -0,0 +1,22 @@
+export class ConversationCoordinator {
+    tails = new Map();
+    async runExclusive(conversationKey, operation) {
+        const previous = this.tails.get(conversationKey) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.then(() => current, () => current);
+        this.tails.set(conversationKey, tail);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.tails.get(conversationKey) === tail) {
+                this.tails.delete(conversationKey);
+            }
+        }
+    }
+}

package/dist/runtime/executor.d.ts

@@ -1,8 +1,9 @@
-import type { BindingCronJobSpec, BindingInboundMessage, BindingLoggerHost, BindingPreparedExecution, BindingRuntimeReport, GatewayBindingModule } from "../binding";
+import type { BindingCronJobSpec, BindingDeliveryTarget, BindingInboundMessage, BindingLoggerHost, BindingPreparedExecution, BindingRuntimeReport, GatewayBindingModule } from "../binding";
 import type { GatewayTextDelivery } from "../delivery/text";
 import type { OpencodeSdkAdapter } from "../opencode/adapter";
 import type { OpencodeEventHub } from "../opencode/events";
 import type { MailboxEntryRecord, SqliteStore } from "../store/sqlite";
+import { ConversationCoordinator } from "./conversation-coordinator";
 export declare class GatewayExecutor {
     private readonly module;
     private readonly store;
@@ -10,15 +11,42 @@ export declare class GatewayExecutor {
     private readonly events;
     private readonly delivery;
     private readonly logger;
-    constructor(module: GatewayBindingModule, store: SqliteStore, opencode: GatewayOpencodeRuntimeLike, events: OpencodeEventHub, delivery: GatewayTextDeliveryLike, logger: BindingLoggerHost);
+    private readonly coordinator;
+    private internalPromptSequence;
+    constructor(module: GatewayBindingModule, store: SqliteStore, opencode: GatewayOpencodeRuntimeLike, events: OpencodeEventHub, delivery: GatewayTextDeliveryLike, logger: BindingLoggerHost, coordinator?: ConversationCoordinator);
     prepareInboundMessage(message: BindingInboundMessage): BindingPreparedExecution;
     handleInboundMessage(message: BindingInboundMessage): Promise<BindingRuntimeReport>;
     executeMailboxEntries(entries: MailboxEntryRecord[]): Promise<BindingRuntimeReport>;
     dispatchCronJob(job: BindingCronJobSpec): Promise<BindingRuntimeReport>;
-    private executePreparedEntries;
+    dispatchScheduledJob(input: DispatchScheduledJobInput): Promise<BindingRuntimeReport>;
+    appendContextToConversation(input: AppendContextToConversationInput): Promise<void>;
+    private executePreparedBatch;
+    private ensureConversationSession;
+    private initializeReplyTargetsIfMissing;
+    private preparePersistedSessionForPrompt;
+    private lookupSession;
+    private createSession;
+    private waitUntilIdle;
+    private appendPrompt;
+    private cleanupResidualBusySession;
+    private abortSessionAndWaitForSettle;
+    private createInternalPromptIdentity;
     private executeDriver;
 }
-export type GatewayExecutorLike = Pick<GatewayExecutor, "handleInboundMessage" | "dispatchCronJob" | "executeMailboxEntries" | "prepareInboundMessage">;
+export type GatewayExecutorLike = Pick<GatewayExecutor, "handleInboundMessage" | "dispatchCronJob" | "dispatchScheduledJob" | "appendContextToConversation" | "executeMailboxEntries" | "prepareInboundMessage">;
+export type DispatchScheduledJobInput = {
+    jobId: string;
+    jobKind: "cron" | "once";
+    conversationKey: string;
+    prompt: string;
+    replyTarget: BindingPreparedExecution["replyTarget"];
+};
+export type AppendContextToConversationInput = {
+    conversationKey: string;
+    replyTarget: BindingDeliveryTarget | null;
+    body: string;
+    recordedAtMs: number;
+};
 type GatewayTextDeliveryLike = Pick<GatewayTextDelivery, "openMany">;
-type GatewayOpencodeRuntimeLike = Pick<OpencodeSdkAdapter, "execute">;
+type GatewayOpencodeRuntimeLike = Pick<OpencodeSdkAdapter, "execute" | "isSessionBusy" | "abortSession">;
 export {};

package/dist/runtime/executor.js

@@ -1,4 +1,7 @@
+import { ConversationCoordinator } from "./conversation-coordinator";
 import { runOpencodeDriver } from "./opencode-runner";
+const SESSION_ABORT_SETTLE_TIMEOUT_MS = 5_000;
+const SESSION_ABORT_POLL_MS = 250;
 export class GatewayExecutor {
     module;
     store;
@@ -6,13 +9,16 @@ export class GatewayExecutor {
     events;
     delivery;
     logger;
-    constructor(module, store, opencode, events, delivery, logger) {
+    coordinator;
+    internalPromptSequence = 0;
+    constructor(module, store, opencode, events, delivery, logger, coordinator = new ConversationCoordinator()) {
         this.module = module;
         this.store = store;
         this.opencode = opencode;
         this.events = events;
         this.delivery = delivery;
         this.logger = logger;
+        this.coordinator = coordinator;
     }
     prepareInboundMessage(message) {
         return this.module.prepareInboundExecution(message);
@@ -52,19 +58,21 @@ export class GatewayExecutor {
         }
         const recordedAtMs = Date.now();
         this.logger.log("info", "handling inbound gateway message");
-        this.store.appendJournal(createJournalEntry("mailbox_flush", recordedAtMs, conversationKey, {
-            entryIds: preparedEntries.map((entry) => entry.entry.id),
-            count: preparedEntries.length,
-        }));
-        for (const entry of preparedEntries) {
-            this.store.appendJournal(createJournalEntry("inbound_message", entry.entry.createdAtMs, conversationKey, {
-                deliveryTarget: entry.prepared.replyTarget,
-                sender: entry.message.sender,
-                text: entry.message.text,
-                attachments: entry.message.attachments,
+        return await this.coordinator.runExclusive(conversationKey, async () => {
+            this.store.appendJournal(createJournalEntry("mailbox_flush", recordedAtMs, conversationKey, {
+                entryIds: preparedEntries.map((entry) => entry.entry.id),
+                count: preparedEntries.length,
             }));
-        }
-        return await this.executePreparedEntries(preparedEntries, recordedAtMs);
+            for (const entry of preparedEntries) {
+                this.store.appendJournal(createJournalEntry("inbound_message", entry.entry.createdAtMs, conversationKey, {
+                    deliveryTarget: entry.prepared.replyTarget,
+                    sender: entry.message.sender,
+                    text: entry.message.text,
+                    attachments: entry.message.attachments,
+                }));
+            }
+            return await this.executePreparedBatch(preparedEntries, recordedAtMs);
+        });
     }
     async dispatchCronJob(job) {
         const prepared = this.module.prepareCronExecution(job);
@@ -80,20 +88,61 @@ export class GatewayExecutor {
             deliveryTarget: prepared.replyTarget?.target ?? null,
             deliveryTopic: prepared.replyTarget?.topic ?? null,
         }));
-        return await this.executePreparedEntries([
-            {
-                entry: null,
-                message: null,
-                prepared,
-            },
-        ], recordedAtMs);
+        return await this.coordinator.runExclusive(prepared.conversationKey, async () => {
+            return await this.executePreparedBatch([
+                {
+                    entry: null,
+                    message: null,
+                    prepared,
+                },
+            ], recordedAtMs);
+        });
     }
-    async executePreparedEntries(entries, recordedAtMs) {
+    async dispatchScheduledJob(input) {
+        const prepared = prepareTextExecution(input.conversationKey, input.prompt, input.replyTarget);
+        const recordedAtMs = Date.now();
+        this.logger.log("info", "dispatching scheduled gateway job");
+        return await this.coordinator.runExclusive(prepared.conversationKey, async () => {
+            this.store.appendJournal(createJournalEntry("cron_dispatch", recordedAtMs, prepared.conversationKey, {
+                id: input.jobId,
+                kind: input.jobKind,
+                promptParts: prepared.promptParts,
+                deliveryChannel: prepared.replyTarget?.channel ?? null,
+                deliveryTarget: prepared.replyTarget?.target ?? null,
+                deliveryTopic: prepared.replyTarget?.topic ?? null,
+            }));
+            return await this.executePreparedBatch([
+                {
+                    entry: null,
+                    message: null,
+                    prepared,
+                },
+            ], recordedAtMs);
+        });
+    }
+    async appendContextToConversation(input) {
+        const conversationKey = normalizeRequiredField(input.conversationKey, "conversation key");
+        const body = normalizeRequiredField(input.body, "context body");
+        await this.coordinator.runExclusive(conversationKey, async () => {
+            const sessionId = await this.ensureConversationSession(conversationKey, input.recordedAtMs, input.replyTarget === null ? [] : [input.replyTarget]);
+            const promptIdentity = this.createInternalPromptIdentity("context", input.recordedAtMs);
+            await this.appendPrompt(sessionId, promptIdentity.messageId, [
+                {
+                    kind: "text",
+                    partId: promptIdentity.partId,
+                    text: body,
+                },
+            ]);
+        });
+    }
+    async executePreparedBatch(entries, recordedAtMs) {
         const conversationKey = entries[0].prepared.conversationKey;
         const persistedSessionId = this.store.getSessionBinding(conversationKey);
+        const preparedSessionId = await this.preparePersistedSessionForPrompt(persistedSessionId);
         const replyTargets = dedupeReplyTargets(entries.flatMap((entry) => (entry.prepared.replyTarget === null ? [] : [entry.prepared.replyTarget])));
         const [deliverySession] = replyTargets.length === 0 ? [null] : await this.delivery.openMany(replyTargets, "auto");
-        const promptResult = await this.executeDriver(entries, recordedAtMs, persistedSessionId, deliverySession, replyTargets);
+        const promptResult = await this.executeDriver(entries, recordedAtMs, preparedSessionId, deliverySession, replyTargets);
+        await this.cleanupResidualBusySession(promptResult.sessionId);
         this.store.putSessionBindingIfUnchanged(conversationKey, persistedSessionId, promptResult.sessionId, recordedAtMs);
         let delivered = false;
         if (deliverySession !== null) {
@@ -112,6 +161,128 @@ export class GatewayExecutor {
             recordedAtMs: BigInt(recordedAtMs),
         };
     }
+    async ensureConversationSession(conversationKey, recordedAtMs, replyTargets) {
+        const persistedSessionId = this.store.getSessionBinding(conversationKey);
+        let sessionId = await this.preparePersistedSessionForPrompt(persistedSessionId);
+        let retryMissingSession = true;
+        for (;;) {
+            if (sessionId === null) {
+                sessionId = await this.createSession(conversationKey);
+            }
+            try {
+                await this.waitUntilIdle(sessionId);
+                break;
+            }
+            catch (error) {
+                if (retryMissingSession && error instanceof MissingSessionCommandError) {
+                    retryMissingSession = false;
+                    sessionId = null;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        this.store.putSessionBindingIfUnchanged(conversationKey, persistedSessionId, sessionId, recordedAtMs);
+        this.initializeReplyTargetsIfMissing(sessionId, conversationKey, replyTargets, recordedAtMs);
+        return sessionId;
+    }
+    initializeReplyTargetsIfMissing(sessionId, conversationKey, replyTargets, recordedAtMs) {
+        if (replyTargets.length === 0 || this.store.listSessionReplyTargets(sessionId).length > 0) {
+            return;
+        }
+        this.store.replaceSessionReplyTargets({
+            sessionId,
+            conversationKey,
+            targets: replyTargets,
+            recordedAtMs,
+        });
+    }
+    async preparePersistedSessionForPrompt(sessionId) {
+        if (sessionId === null) {
+            return null;
+        }
+        const found = await this.lookupSession(sessionId);
+        if (!found) {
+            return null;
+        }
+        if (!(await this.opencode.isSessionBusy(sessionId))) {
+            return sessionId;
+        }
+        this.logger.log("warn", `aborting busy gateway session before prompt dispatch: ${sessionId}`);
+        try {
+            await this.abortSessionAndWaitForSettle(sessionId);
+            return sessionId;
+        }
+        catch (error) {
+            this.logger.log("warn", `busy gateway session did not settle and will be replaced: ${sessionId}: ${extractErrorMessage(error)}`);
+            return null;
+        }
+    }
+    async lookupSession(sessionId) {
+        const result = await this.opencode.execute({
+            kind: "lookupSession",
+            sessionId,
+        });
+        const lookup = expectCommandResult(result, "lookupSession");
+        return lookup.found;
+    }
+    async createSession(conversationKey) {
+        const result = await this.opencode.execute({
+            kind: "createSession",
+            title: `Gateway ${conversationKey}`,
+        });
+        return expectCommandResult(result, "createSession").sessionId;
+    }
+    async waitUntilIdle(sessionId) {
+        const result = await this.opencode.execute({
+            kind: "waitUntilIdle",
+            sessionId,
+        });
+        expectCommandResult(result, "waitUntilIdle");
+    }
+    async appendPrompt(sessionId, messageId, parts) {
+        const result = await this.opencode.execute({
+            kind: "appendPrompt",
+            sessionId,
+            messageId,
+            parts,
+        });
+        expectCommandResult(result, "appendPrompt");
+    }
+    async cleanupResidualBusySession(sessionId) {
+        if (!(await this.opencode.isSessionBusy(sessionId))) {
+            return;
+        }
+        this.logger.log("warn", `aborting residual busy gateway session after prompt completion: ${sessionId}`);
+        try {
+            await this.abortSessionAndWaitForSettle(sessionId);
+        }
+        catch (error) {
+            this.logger.log("warn", `residual busy gateway session did not settle after abort: ${sessionId}: ${extractErrorMessage(error)}`);
+        }
+    }
+    async abortSessionAndWaitForSettle(sessionId) {
+        await this.opencode.abortSession(sessionId);
+        const deadline = Date.now() + SESSION_ABORT_SETTLE_TIMEOUT_MS;
+        for (;;) {
+            if (!(await this.opencode.isSessionBusy(sessionId))) {
+                return;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`session remained busy after abort for ${SESSION_ABORT_SETTLE_TIMEOUT_MS}ms`);
+            }
+            await Bun.sleep(SESSION_ABORT_POLL_MS);
+        }
+    }
+    createInternalPromptIdentity(prefix, recordedAtMs) {
+        const suffix = `${recordedAtMs}_${this.internalPromptSequence}`;
+        this.internalPromptSequence += 1;
+        const normalizedPrefix = prefix.replaceAll(":", "_");
+        return {
+            messageId: `msg_gateway_${normalizedPrefix}_${suffix}`,
+            partId: `prt_gateway_${normalizedPrefix}_${suffix}_0`,
+        };
+    }
     async executeDriver(entries, recordedAtMs, persistedSessionId, deliverySession, replyTargets) {
         return await runOpencodeDriver({
             module: this.module,
@@ -143,6 +314,18 @@ function createJournalEntry(kind, recordedAtMs, conversationKey, payload) {
         payload,
     };
 }
+function prepareTextExecution(conversationKey, prompt, replyTarget) {
+    return {
+        conversationKey: normalizeRequiredField(conversationKey, "conversation key"),
+        promptParts: [
+            {
+                kind: "text",
+                text: normalizeRequiredField(prompt, "schedule prompt"),
+            },
+        ],
+        replyTarget,
+    };
+}
 function mailboxEntryToInboundMessage(entry) {
     return {
         deliveryTarget: {
@@ -174,6 +357,30 @@ function normalizeRequiredField(value, field) {
     }
     return trimmed;
 }
+function extractErrorMessage(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message;
+    }
+    return String(error);
+}
+function expectCommandResult(result, expectedKind) {
+    if (result.kind === "error") {
+        if (result.code === "missingSession") {
+            throw new MissingSessionCommandError(result.message);
+        }
+        throw new Error(result.message);
+    }
+    if (result.kind !== expectedKind) {
+        throw new Error(`unexpected OpenCode result kind: expected ${expectedKind}, received ${result.kind}`);
+    }
+    return result;
+}
+class MissingSessionCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MissingSessionCommandError";
+    }
+}
 function createPromptKey(entry, recordedAtMs, index) {
     if (entry.entry !== null) {
         return `mailbox:${entry.entry.id}:${recordedAtMs}`;

package/dist/runtime/runtime-singleton.d.ts

@@ -0,0 +1,2 @@
+export declare function getOrCreateRuntimeSingleton<T>(key: string, factory: () => Promise<T>): Promise<T>;
+export declare function clearRuntimeSingletonForTests(key: string): void;

package/dist/runtime/runtime-singleton.js

@@ -0,0 +1,28 @@
+const RUNTIME_CACHE_KEY = Symbol.for("opencode-gateway.runtime-cache");
+export function getOrCreateRuntimeSingleton(key, factory) {
+    const cache = getRuntimeCache();
+    const existing = cache.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const promise = factory().catch((error) => {
+        if (cache.get(key) === promise) {
+            cache.delete(key);
+        }
+        throw error;
+    });
+    cache.set(key, promise);
+    return promise;
+}
+export function clearRuntimeSingletonForTests(key) {
+    getRuntimeCache().delete(key);
+}
+function getRuntimeCache() {
+    const globalScope = globalThis;
+    let cache = globalScope[RUNTIME_CACHE_KEY];
+    if (cache === undefined) {
+        cache = new Map();
+        globalScope[RUNTIME_CACHE_KEY] = cache;
+    }
+    return cache;
+}

package/dist/session/context.js

@@ -31,6 +31,10 @@ export class GatewaySessionContext {
                 `- Current reply topic: ${target.topic ?? "none"}`,
                 "- Unless the user explicitly asks otherwise, channel-aware actions should default to this target.",
                 "- If the user asks to start a fresh channel session, use channel_new_session.",
+                "- If the user asks for a one-shot reminder or relative-time follow-up, prefer schedule_once.",
+                "- If the user asks for a recurring schedule, prefer cron_upsert.",
+                "- Use schedule_list and schedule_status to inspect existing scheduled jobs and recent run results.",
+                "- Scheduled results delivered to this channel are automatically appended to this session as context.",
             ].join("\n");
         }
         return [
@@ -39,6 +43,8 @@ export class GatewaySessionContext {
             ...targets.map((target, index) => `- Target ${index + 1}: channel=${target.channel}, id=${target.target}, topic=${target.topic ?? "none"}`),
             "- If a tool needs a single explicit target, do not guess; ask the user or use explicit tool arguments.",
             "- If the user asks to start a fresh channel session for this route, use channel_new_session.",
+            "- Prefer schedule_once for one-shot reminders and cron_upsert for recurring schedules.",
+            "- Use schedule_list and schedule_status to inspect scheduled jobs and recent run results.",
         ].join("\n");
     }
 }

package/dist/store/migrations.js

@@ -1,4 +1,4 @@
-const LATEST_SCHEMA_VERSION = 6;
+const LATEST_SCHEMA_VERSION = 7;
 export function migrateGatewayDatabase(db) {
     db.exec("PRAGMA journal_mode = WAL;");
     db.exec("PRAGMA foreign_keys = ON;");
@@ -28,6 +28,10 @@ export function migrateGatewayDatabase(db) {
     }
     if (currentVersion === 5) {
         migrateToV6(db);
+        currentVersion = 6;
+    }
+    if (currentVersion === 6) {
+        migrateToV7(db);
     }
 }
 function readUserVersion(db) {
@@ -179,5 +183,15 @@ function migrateToV6(db) {
         CREATE INDEX pending_questions_session_id_created_at_ms_idx
             ON pending_questions (session_id, created_at_ms);
     `);
+    db.exec("PRAGMA user_version = 6;");
+}
+function migrateToV7(db) {
+    db.exec(`
+        ALTER TABLE cron_jobs
+        ADD COLUMN kind TEXT NOT NULL DEFAULT 'cron';
+
+        ALTER TABLE cron_jobs
+        ADD COLUMN run_at_ms INTEGER;
+    `);
     db.exec(`PRAGMA user_version = ${LATEST_SCHEMA_VERSION};`);
 }

package/dist/store/sqlite.d.ts

@@ -3,6 +3,17 @@ import type { BindingDeliveryTarget } from "../binding";
 import type { GatewayQuestionInfo, PendingQuestionRecord } from "../questions/types";
 export type RuntimeJournalKind = "inbound_message" | "cron_dispatch" | "delivery" | "mailbox_enqueue" | "mailbox_flush";
 export type CronRunStatus = "running" | "succeeded" | "failed" | "abandoned";
+export type ScheduleJobKind = "cron" | "once";
+export type CronRunRecord = {
+    id: number;
+    jobId: string;
+    scheduledForMs: number;
+    startedAtMs: number;
+    finishedAtMs: number | null;
+    status: CronRunStatus;
+    responseText: string | null;
+    errorMessage: string | null;
+};
 export type RuntimeJournalEntry = {
     kind: RuntimeJournalKind;
     recordedAtMs: number;
@@ -11,7 +22,9 @@ export type RuntimeJournalEntry = {
 };
 export type CronJobRecord = {
     id: string;
-    schedule: string;
+    kind: ScheduleJobKind;
+    schedule: string | null;
+    runAtMs: number | null;
     prompt: string;
     deliveryChannel: string | null;
     deliveryTarget: string | null;
@@ -43,7 +56,9 @@ export type MailboxEntryAttachmentRecord = {
 };
 export type PersistCronJobInput = {
     id: string;
-    schedule: string;
+    kind: ScheduleJobKind;
+    schedule: string | null;
+    runAtMs: number | null;
     prompt: string;
     deliveryChannel: string | null;
     deliveryTarget: string | null;
@@ -119,6 +134,8 @@ export declare class SqliteStore {
     listDueCronJobs(nowMs: number, limit: number): CronJobRecord[];
     removeCronJob(id: string): boolean;
     updateCronJobNextRun(id: string, nextRunAtMs: number, recordedAtMs: number): void;
+    setCronJobEnabled(id: string, enabled: boolean, recordedAtMs: number): void;
+    listCronRuns(jobId: string, limit: number): CronRunRecord[];
     insertCronRun(jobId: string, scheduledForMs: number, startedAtMs: number): number;
     finishCronRun(runId: number, status: Exclude<CronRunStatus, "running">, finishedAtMs: number, responseText: string | null, errorMessage: string | null): void;
     abandonRunningCronRuns(finishedAtMs: number): number;