opencode-gateway 0.1.0 → 0.2.0

package/dist/session/context.js

@@ -17,28 +17,7 @@ export class GatewaySessionContext {
     getDefaultReplyTarget(sessionId) {
         return this.store.getDefaultSessionReplyTarget(sessionId);
     }
-    buildSystemPrompt(sessionId) {
-        const targets = this.listReplyTargets(sessionId);
-        if (targets.length === 0) {
-            return null;
-        }
-        if (targets.length === 1) {
-            const target = targets[0];
-            return [
-                "Gateway context:",
-                `- Current message source channel: ${target.channel}`,
-                `- Current reply target id: ${target.target}`,
-                `- 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.",
-            ].join("\n");
-        }
-        return [
-            "Gateway context:",
-            `- This session currently fans out to ${targets.length} reply targets.`,
-            ...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.",
-        ].join("\n");
+    isGatewaySession(sessionId) {
+        return this.store.hasGatewaySession(sessionId);
     }
 }

package/dist/session/system-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { GatewayMemoryPromptProvider } from "../memory/prompt";
+import type { GatewaySessionContext } from "./context";
+export declare class GatewaySystemPromptBuilder {
+    private readonly sessions;
+    private readonly memory;
+    constructor(sessions: GatewaySessionContext, memory: GatewayMemoryPromptProvider);
+    buildPrompts(sessionId: string): Promise<string[]>;
+}

package/dist/session/system-prompt.js

@@ -0,0 +1,52 @@
+export class GatewaySystemPromptBuilder {
+    sessions;
+    memory;
+    constructor(sessions, memory) {
+        this.sessions = sessions;
+        this.memory = memory;
+    }
+    async buildPrompts(sessionId) {
+        if (!this.sessions.isGatewaySession(sessionId)) {
+            return [];
+        }
+        const prompts = [];
+        const gatewayPrompt = buildGatewayContextPrompt(this.sessions.listReplyTargets(sessionId));
+        if (gatewayPrompt !== null) {
+            prompts.push(gatewayPrompt);
+        }
+        const memoryPrompt = await this.memory.buildPrompt();
+        if (memoryPrompt !== null) {
+            prompts.push(memoryPrompt);
+        }
+        return prompts;
+    }
+}
+function buildGatewayContextPrompt(targets) {
+    if (targets.length === 0) {
+        return null;
+    }
+    if (targets.length === 1) {
+        const target = targets[0];
+        return [
+            "Gateway context:",
+            `- Current message source channel: ${target.channel}`,
+            `- Current reply target id: ${target.target}`,
+            `- 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 [
+        "Gateway context:",
+        `- This session currently fans out to ${targets.length} reply targets.`,
+        ...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;
@@ -97,6 +112,7 @@ export declare class SqliteStore {
     replaceSessionReplyTargets(input: PersistSessionReplyTargetsInput): void;
     listSessionReplyTargets(sessionId: string): BindingDeliveryTarget[];
     getDefaultSessionReplyTarget(sessionId: string): BindingDeliveryTarget | null;
+    hasGatewaySession(sessionId: string): boolean;
     appendJournal(entry: RuntimeJournalEntry): void;
     replacePendingQuestion(input: PersistPendingQuestionInput): void;
     deletePendingQuestion(requestId: string): void;
@@ -119,6 +135,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;

package/dist/store/sqlite.js

@@ -109,6 +109,28 @@ export class SqliteStore {
             .get(sessionId);
         return row ? mapSessionReplyTargetRow(row) : null;
     }
+    hasGatewaySession(sessionId) {
+        const binding = this.db
+            .query(`
+                    SELECT 1 AS present
+                    FROM session_bindings
+                    WHERE session_id = ?1
+                    LIMIT 1;
+                `)
+            .get(sessionId);
+        if (binding?.present === 1) {
+            return true;
+        }
+        const replyTarget = this.db
+            .query(`
+                    SELECT 1 AS present
+                    FROM session_reply_targets
+                    WHERE session_id = ?1
+                    LIMIT 1;
+                `)
+            .get(sessionId);
+        return replyTarget?.present === 1;
+    }
     appendJournal(entry) {
         this.db
             .query(`
@@ -315,11 +337,16 @@ export class SqliteStore {
     upsertCronJob(input) {
         assertSafeInteger(input.nextRunAtMs, "cron next_run_at_ms");
         assertSafeInteger(input.recordedAtMs, "cron recordedAtMs");
+        if (input.runAtMs !== null) {
+            assertSafeInteger(input.runAtMs, "cron run_at_ms");
+        }
         this.db
             .query(`
                     INSERT INTO cron_jobs (
                         id,
+                        kind,
                         schedule,
+                        run_at_ms,
                         prompt,
                         delivery_channel,
                         delivery_target,
@@ -329,9 +356,11 @@ export class SqliteStore {
                         created_at_ms,
                         updated_at_ms
                     )
-                    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?9)
+                    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11)
                     ON CONFLICT(id) DO UPDATE SET
+                        kind = excluded.kind,
                         schedule = excluded.schedule,
+                        run_at_ms = excluded.run_at_ms,
                         prompt = excluded.prompt,
                         delivery_channel = excluded.delivery_channel,
                         delivery_target = excluded.delivery_target,
@@ -340,14 +369,16 @@ export class SqliteStore {
                         next_run_at_ms = excluded.next_run_at_ms,
                         updated_at_ms = excluded.updated_at_ms;
                 `)
-            .run(input.id, input.schedule, input.prompt, input.deliveryChannel, input.deliveryTarget, input.deliveryTopic, input.enabled ? 1 : 0, input.nextRunAtMs, input.recordedAtMs);
+            .run(input.id, input.kind, encodeStoredSchedule(input.kind, input.schedule), input.runAtMs, input.prompt, input.deliveryChannel, input.deliveryTarget, input.deliveryTopic, input.enabled ? 1 : 0, input.nextRunAtMs, input.recordedAtMs);
     }
     getCronJob(id) {
         const row = this.db
             .query(`
                     SELECT
                         id,
+                        kind,
                         schedule,
+                        run_at_ms,
                         prompt,
                         delivery_channel,
                         delivery_target,
@@ -367,7 +398,9 @@ export class SqliteStore {
             .query(`
                     SELECT
                         id,
+                        kind,
                         schedule,
+                        run_at_ms,
                         prompt,
                         delivery_channel,
                         delivery_target,
@@ -388,7 +421,9 @@ export class SqliteStore {
             .query(`
                     SELECT
                         id,
+                        kind,
                         schedule,
+                        run_at_ms,
                         prompt,
                         delivery_channel,
                         delivery_target,
@@ -398,7 +433,7 @@ export class SqliteStore {
                         created_at_ms,
                         updated_at_ms
                     FROM cron_jobs
-                    WHERE enabled = 1 AND next_run_at_ms <= ?1
+                    WHERE kind = 'cron' AND enabled = 1 AND next_run_at_ms <= ?1
                     ORDER BY next_run_at_ms ASC, id ASC;
                 `)
             .all(nowMs);
@@ -411,7 +446,9 @@ export class SqliteStore {
             .query(`
                     SELECT
                         id,
+                        kind,
                         schedule,
+                        run_at_ms,
                         prompt,
                         delivery_channel,
                         delivery_target,
@@ -443,6 +480,47 @@ export class SqliteStore {
                 `)
             .run(id, nextRunAtMs, recordedAtMs);
     }
+    setCronJobEnabled(id, enabled, recordedAtMs) {
+        assertSafeInteger(recordedAtMs, "cron recordedAtMs");
+        this.db
+            .query(`
+                    UPDATE cron_jobs
+                    SET enabled = ?2,
+                        updated_at_ms = ?3
+                    WHERE id = ?1;
+                `)
+            .run(id, enabled ? 1 : 0, recordedAtMs);
+    }
+    listCronRuns(jobId, limit) {
+        assertSafeInteger(limit, "cron run limit");
+        const rows = this.db
+            .query(`
+                    SELECT
+                        id,
+                        job_id,
+                        scheduled_for_ms,
+                        started_at_ms,
+                        finished_at_ms,
+                        status,
+                        response_text,
+                        error_message
+                    FROM cron_runs
+                    WHERE job_id = ?1
+                    ORDER BY started_at_ms DESC, id DESC
+                    LIMIT ?2;
+                `)
+            .all(jobId, limit);
+        return rows.map((row) => ({
+            id: row.id,
+            jobId: row.job_id,
+            scheduledForMs: row.scheduled_for_ms,
+            startedAtMs: row.started_at_ms,
+            finishedAtMs: row.finished_at_ms,
+            status: row.status,
+            responseText: row.response_text,
+            errorMessage: row.error_message,
+        }));
+    }
     insertCronRun(jobId, scheduledForMs, startedAtMs) {
         assertSafeInteger(scheduledForMs, "cron scheduled_for_ms");
         assertSafeInteger(startedAtMs, "cron started_at_ms");
@@ -496,9 +574,12 @@ export class SqliteStore {
     }
 }
 function mapCronJobRow(row) {
+    const kind = parseScheduleJobKind(row.kind);
     return {
         id: row.id,
-        schedule: row.schedule,
+        kind,
+        schedule: kind === "cron" ? row.schedule : null,
+        runAtMs: row.run_at_ms,
         prompt: row.prompt,
         deliveryChannel: row.delivery_channel,
         deliveryTarget: row.delivery_target,
@@ -509,6 +590,24 @@ function mapCronJobRow(row) {
         updatedAtMs: row.updated_at_ms,
     };
 }
+function parseScheduleJobKind(value) {
+    switch (value) {
+        case "cron":
+        case "once":
+            return value;
+        default:
+            throw new Error(`stored schedule job kind is invalid: ${value}`);
+    }
+}
+function encodeStoredSchedule(kind, schedule) {
+    if (kind === "once") {
+        return "@once";
+    }
+    if (schedule === null) {
+        throw new Error("cron schedule must not be null");
+    }
+    return schedule;
+}
 function mapMailboxEntryRow(row, attachments) {
     return {
         id: row.id,

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

@@ -5,3 +5,8 @@ export declare function resolveToolDeliveryTarget(args: {
     target?: string;
     topic?: string;
 }, sessionId: string | null | undefined, sessions: GatewaySessionContext): BindingDeliveryTarget;
+export declare function resolveOptionalToolDeliveryTarget(args: {
+    channel?: string;
+    target?: string;
+    topic?: string;
+}, sessionId: string | null | undefined, sessions: GatewaySessionContext): BindingDeliveryTarget | null;

package/dist/tools/channel-target.js

@@ -9,6 +9,12 @@ export function resolveToolDeliveryTarget(args, sessionId, sessions) {
         topic,
     };
 }
+export function resolveOptionalToolDeliveryTarget(args, sessionId, sessions) {
+    if (args.channel === undefined && args.target === undefined && args.topic === undefined) {
+        return sessionId ? sessions.getDefaultReplyTarget(sessionId) : null;
+    }
+    return resolveToolDeliveryTarget(args, sessionId, sessions);
+}
 function normalizeRequired(value, field) {
     if (value === null) {
         throw new Error(`${field} is required when the current session has no default reply target`);

package/dist/tools/cron-run.js

@@ -1,7 +1,7 @@
 import { tool } from "@opencode-ai/plugin";
 export function createCronRunTool(runtime) {
     return tool({
-        description: "Run one persisted gateway cron job immediately without changing its schedule",
+        description: "Run one persisted gateway schedule job immediately without changing its schedule metadata.",
         args: {
             id: tool.schema.string().min(1),
         },

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

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

package/dist/tools/cron-upsert.js

@@ -1,8 +1,9 @@
 import { tool } from "@opencode-ai/plugin";
+import { resolveOptionalToolDeliveryTarget } from "./channel-target";
 import { formatUnixMsAsUtc, formatUnixMsInTimeZone } from "./time";
-export function createCronUpsertTool(runtime) {
+export function createCronUpsertTool(runtime, sessions) {
     return tool({
-        description: "Create or replace a persisted gateway cron job. The schedule uses cron.timezone or the runtime local time zone.",
+        description: "Create or replace a recurring gateway cron job. When called from a channel-backed session, delivery defaults to the current reply target.",
         args: {
             id: tool.schema.string().min(1),
             schedule: tool.schema.string().min(1),
@@ -12,26 +13,39 @@ export function createCronUpsertTool(runtime) {
             delivery_target: tool.schema.string().optional(),
             delivery_topic: tool.schema.string().optional(),
         },
-        async execute(args) {
+        async execute(args, context) {
+            const deliveryTarget = resolveOptionalToolDeliveryTarget({
+                channel: args.delivery_channel,
+                target: args.delivery_target,
+                topic: args.delivery_topic,
+            }, context.sessionID, sessions);
             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,
+                deliveryChannel: deliveryTarget?.channel ?? null,
+                deliveryTarget: deliveryTarget?.target ?? null,
+                deliveryTopic: deliveryTarget?.topic ?? null,
             });
             return [
                 `id=${job.id}`,
+                `kind=${job.kind}`,
                 `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)}`,
             ].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-list.d.ts → schedule-cancel.d.ts}

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

package/dist/tools/schedule-cancel.js

@@ -0,0 +1,12 @@
+import { tool } from "@opencode-ai/plugin";
+export function createScheduleCancelTool(runtime) {
+    return tool({
+        description: "Cancel a persisted gateway schedule job without deleting its run history.",
+        args: {
+            id: tool.schema.string().min(1),
+        },
+        async execute(args) {
+            return runtime.cancelJob(args.id) ? `canceled=${args.id}` : `inactive=${args.id}`;
+        },
+    });
+}

package/dist/tools/schedule-format.d.ts

@@ -0,0 +1,4 @@
+import type { ScheduleJobStatus } from "../cron/runtime";
+import type { CronJobRecord } from "../store/sqlite";
+export declare function formatScheduleJob(job: CronJobRecord, timeZone: string): string;
+export declare function formatScheduleStatus(status: ScheduleJobStatus, timeZone: string): string;

package/dist/tools/schedule-format.js

@@ -0,0 +1,48 @@
+import { formatUnixMsAsUtc, formatUnixMsInTimeZone } from "./time";
+export function formatScheduleJob(job, timeZone) {
+    const lines = [`id=${job.id}`, `kind=${job.kind}`, `enabled=${job.enabled}`];
+    if (job.kind === "cron") {
+        lines.push(`schedule=${job.schedule}`);
+        lines.push(`timezone=${timeZone}`);
+        lines.push(`next_run_at_ms=${job.nextRunAtMs}`);
+        lines.push(`next_run_at_local=${formatUnixMsInTimeZone(job.nextRunAtMs, timeZone)}`);
+        lines.push(`next_run_at_utc=${formatUnixMsAsUtc(job.nextRunAtMs)}`);
+    }
+    else {
+        lines.push(`run_at_ms=${job.runAtMs ?? "none"}`);
+        if (job.runAtMs !== null) {
+            lines.push(`run_at_local=${formatUnixMsInTimeZone(job.runAtMs, timeZone)}`);
+            lines.push(`run_at_utc=${formatUnixMsAsUtc(job.runAtMs)}`);
+        }
+    }
+    lines.push(`delivery=${formatDelivery(job.deliveryChannel, job.deliveryTarget, job.deliveryTopic)}`);
+    lines.push(`prompt=${job.prompt}`);
+    return lines.join("\n");
+}
+export function formatScheduleStatus(status, timeZone) {
+    const lines = [formatScheduleJob(status.job, timeZone), `state=${status.state}`];
+    if (status.runs.length === 0) {
+        lines.push("runs=none");
+        return lines.join("\n");
+    }
+    lines.push("");
+    lines.push(...status.runs.map((run, index) => formatRun(run, index + 1)));
+    return lines.join("\n");
+}
+function formatRun(run, ordinal) {
+    return [
+        `run[${ordinal}].id=${run.id}`,
+        `run[${ordinal}].status=${run.status}`,
+        `run[${ordinal}].scheduled_for_ms=${run.scheduledForMs}`,
+        `run[${ordinal}].started_at_ms=${run.startedAtMs}`,
+        `run[${ordinal}].finished_at_ms=${run.finishedAtMs ?? "none"}`,
+        `run[${ordinal}].response_text=${run.responseText ?? "none"}`,
+        `run[${ordinal}].error_message=${run.errorMessage ?? "none"}`,
+    ].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 → schedule-list.d.ts}

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

package/dist/tools/schedule-list.js

@@ -0,0 +1,17 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatScheduleJob } from "./schedule-format";
+export function createScheduleListTool(runtime) {
+    return tool({
+        description: "List persisted gateway schedule jobs, including recurring cron jobs and one-shot timers.",
+        args: {
+            include_terminal: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+            const jobs = runtime.listJobs(args.include_terminal ?? false);
+            if (jobs.length === 0) {
+                return "no scheduled jobs";
+            }
+            return jobs.map((job) => formatScheduleJob(job, runtime.timeZone())).join("\n\n");
+        },
+    });
+}

package/dist/tools/schedule-once.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { GatewayCronRuntime } from "../cron/runtime";
+import type { GatewaySessionContext } from "../session/context";
+export declare function createScheduleOnceTool(runtime: GatewayCronRuntime, sessions: GatewaySessionContext): ToolDefinition;

package/dist/tools/schedule-once.js

@@ -0,0 +1,43 @@
+import { tool } from "@opencode-ai/plugin";
+import { resolveOptionalToolDeliveryTarget } from "./channel-target";
+import { formatScheduleJob } from "./schedule-format";
+export function createScheduleOnceTool(runtime, sessions) {
+    return tool({
+        description: "Schedule a one-shot gateway job. When called from a channel-backed session, delivery defaults to the current reply target.",
+        args: {
+            id: tool.schema.string().min(1),
+            prompt: tool.schema.string().min(1),
+            delay_seconds: tool.schema.number().optional(),
+            run_at_ms: tool.schema.number().optional(),
+            delivery_channel: tool.schema.string().optional(),
+            delivery_target: tool.schema.string().optional(),
+            delivery_topic: tool.schema.string().optional(),
+        },
+        async execute(args, context) {
+            const deliveryTarget = resolveOptionalToolDeliveryTarget({
+                channel: args.delivery_channel,
+                target: args.delivery_target,
+                topic: args.delivery_topic,
+            }, context.sessionID, sessions);
+            const job = runtime.scheduleOnce({
+                id: args.id,
+                prompt: args.prompt,
+                delaySeconds: normalizeOptionalInteger(args.delay_seconds, "delay_seconds"),
+                runAtMs: normalizeOptionalInteger(args.run_at_ms, "run_at_ms"),
+                deliveryChannel: deliveryTarget?.channel ?? null,
+                deliveryTarget: deliveryTarget?.target ?? null,
+                deliveryTopic: deliveryTarget?.topic ?? null,
+            });
+            return formatScheduleJob(job, runtime.timeZone());
+        },
+    });
+}
+function normalizeOptionalInteger(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`${field} must be an integer`);
+    }
+    return value;
+}

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

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

package/dist/tools/schedule-status.js

@@ -0,0 +1,23 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatScheduleStatus } from "./schedule-format";
+export function createScheduleStatusTool(runtime) {
+    return tool({
+        description: "Inspect one persisted gateway schedule job and its recent run history.",
+        args: {
+            id: tool.schema.string().min(1),
+            limit: tool.schema.number().optional(),
+        },
+        async execute(args) {
+            return formatScheduleStatus(runtime.getJobStatus(args.id, normalizeOptionalLimit(args.limit)), runtime.timeZone());
+        },
+    });
+}
+function normalizeOptionalLimit(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new Error("limit must be an integer");
+    }
+    return value;
+}