opencode-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M4n5ter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# opencode-gateway
+
+Gateway plugin for OpenCode.
+
+## Quick Start
+
+Initialize your OpenCode config:
+
+```bash
+npx opencode-gateway init
+```
+
+This ensures:
+
+- `plugin: ["opencode-gateway"]` exists in `opencode.json`
+- `opencode-gateway.toml` exists next to `opencode.json`
+
+By default the CLI uses `OPENCODE_CONFIG_DIR` when it is set, otherwise it
+writes to:
+
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/opencode-gateway.toml`
+
+Check what it resolved:
+
+```bash
+npx opencode-gateway doctor
+```
+
+Then start OpenCode normally:
+
+```bash
+opencode serve
+```
+
+If you want a separate managed config tree instead of editing your existing
+OpenCode config:
+
+```bash
+npx opencode-gateway init --managed
+export OPENCODE_CONFIG="$HOME/.config/opencode-gateway/opencode/opencode.json"
+export OPENCODE_CONFIG_DIR="$HOME/.config/opencode-gateway/opencode"
+opencode serve
+```
+
+## Example gateway config
+
+```toml
+[gateway]
+state_db = "/home/you/.local/share/opencode-gateway/state.db"
+
+[cron]
+enabled = true
+tick_seconds = 5
+max_concurrent_runs = 1
+
+[channels.telegram]
+enabled = false
+bot_token_env = "TELEGRAM_BOT_TOKEN"
+poll_timeout_seconds = 25
+allowed_chats = []
+allowed_users = []
+```
+
+When Telegram is enabled, export the bot token through the configured
+environment variable, for example:
+
+```bash
+export TELEGRAM_BOT_TOKEN="..."
+```

package/dist/binding/execution.d.ts

@@ -0,0 +1,24 @@
+export type BindingExecutionObservation = {
+    kind: "messageUpdated";
+    sessionId: string;
+    messageId: string;
+    role: string;
+    parentId: string | null;
+} | {
+    kind: "textPartUpdated";
+    sessionId: string;
+    messageId: string;
+    partId: string;
+    text: string | null;
+    delta: string | null;
+    ignored: boolean;
+} | {
+    kind: "textPartDelta";
+    messageId: string;
+    partId: string;
+    delta: string;
+};
+export type BindingProgressiveDirective = {
+    kind: string;
+    text: string | null;
+};

package/dist/binding/execution.js

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

package/dist/binding/gateway.d.ts

@@ -0,0 +1,71 @@
+export type GatewayStatusSnapshot = {
+    runtimeMode: string;
+    supportsTelegram: boolean;
+    supportsCron: boolean;
+    hasWebUi: boolean;
+};
+export type BindingCronJobSpec = {
+    id: string;
+    schedule: string;
+    prompt: string;
+    deliveryChannel: string | null;
+    deliveryTarget: string | null;
+    deliveryTopic: string | null;
+};
+export type BindingRuntimeReport = {
+    conversationKey: string;
+    responseText: string;
+    delivered: boolean;
+    recordedAtMs: bigint;
+};
+export type BindingHostAck = {
+    errorMessage: string | null;
+};
+export type BindingDeliveryTarget = {
+    channel: string;
+    target: string;
+    topic: string | null;
+};
+export type BindingInboundAttachment = {
+    kind: "image";
+    mimeType: string;
+    fileName: string | null;
+    localPath: string;
+};
+export type BindingInboundMessage = {
+    deliveryTarget: BindingDeliveryTarget;
+    sender: string;
+    text: string | null;
+    attachments: BindingInboundAttachment[];
+    mailboxKey?: string | null;
+};
+export type BindingPromptPart = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "file";
+    mimeType: string;
+    fileName: string | null;
+    localPath: string;
+};
+export type BindingPreparedExecution = {
+    conversationKey: string;
+    promptParts: BindingPromptPart[];
+    replyTarget: BindingDeliveryTarget | null;
+};
+export type BindingOutboundMessage = {
+    deliveryTarget: BindingDeliveryTarget;
+    body: string;
+};
+export type BindingTransportHost = {
+    sendMessage(message: BindingOutboundMessage): Promise<BindingHostAck>;
+};
+export type BindingLoggerHost = {
+    log(level: string, message: string): void;
+};
+export type GatewayContract = {
+    gatewayStatus(): GatewayStatusSnapshot;
+    conversationKeyForDeliveryTarget(target: BindingDeliveryTarget): string;
+    nextCronRunAt(job: BindingCronJobSpec, afterMs: number, timeZone: string): number;
+    normalizeCronTimeZone(timeZone: string): string;
+};

package/dist/binding/gateway.js

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

package/dist/binding/index.d.ts

@@ -0,0 +1,15 @@
+import type { BindingCronJobSpec, BindingInboundMessage, BindingPreparedExecution, GatewayContract } from "./gateway";
+import type { BindingOpencodeExecutionInput, OpencodeExecutionDriver } from "./opencode";
+export type { BindingExecutionObservation, BindingProgressiveDirective } from "./execution";
+export type { BindingCronJobSpec, BindingDeliveryTarget, BindingHostAck, BindingInboundAttachment, BindingInboundMessage, BindingLoggerHost, BindingOutboundMessage, BindingPreparedExecution, BindingPromptPart, BindingRuntimeReport, BindingTransportHost, GatewayContract, GatewayStatusSnapshot, } from "./gateway";
+export type { BindingOpencodeCommand, BindingOpencodeCommandPart, BindingOpencodeCommandResult, BindingOpencodeDriverStep, BindingOpencodeExecutionInput, BindingOpencodeMessage, BindingOpencodeMessagePart, BindingOpencodePrompt, OpencodeExecutionDriver, } from "./opencode";
+export type GatewayBindingModule = GatewayContract & {
+    prepareInboundExecution: (message: BindingInboundMessage) => BindingPreparedExecution;
+    prepareCronExecution: (job: BindingCronJobSpec) => BindingPreparedExecution;
+    OpencodeExecutionDriver: {
+        new (input: BindingOpencodeExecutionInput): OpencodeExecutionDriver;
+    };
+    initSync?: (module?: BufferSource | WebAssembly.Module) => unknown;
+    default?: (module?: BufferSource | WebAssembly.Module) => Promise<unknown>;
+};
+export declare function loadGatewayBindingModule(): Promise<GatewayBindingModule>;

package/dist/binding/index.js

@@ -0,0 +1,4 @@
+const GENERATED_NODE_ENTRYPOINT = new URL("../../generated/wasm/pkg/opencode_gateway_ffi.js", import.meta.url);
+export async function loadGatewayBindingModule() {
+    return (await import(GENERATED_NODE_ENTRYPOINT.href));
+}

package/dist/binding/opencode.d.ts

@@ -0,0 +1,123 @@
+import type { BindingExecutionObservation, BindingProgressiveDirective } from "./execution";
+import type { BindingPromptPart } from "./gateway";
+export type BindingOpencodePrompt = {
+    promptKey: string;
+    parts: BindingPromptPart[];
+};
+export type BindingOpencodeExecutionInput = {
+    conversationKey: string;
+    persistedSessionId: string | null;
+    mode: "progressive" | "oneshot";
+    flushIntervalMs: number;
+    prompts: BindingOpencodePrompt[];
+};
+export type BindingOpencodeMessagePart = {
+    messageId: string;
+    partId: string;
+    type: string;
+    text: string | null;
+    ignored: boolean;
+};
+export type BindingOpencodeMessage = {
+    messageId: string;
+    role: string;
+    parentId: string | null;
+    parts: BindingOpencodeMessagePart[];
+};
+export type BindingOpencodeCommand = {
+    kind: "lookupSession";
+    sessionId: string;
+} | {
+    kind: "createSession";
+    title: string;
+} | {
+    kind: "waitUntilIdle";
+    sessionId: string;
+} | {
+    kind: "appendPrompt";
+    sessionId: string;
+    messageId: string;
+    parts: BindingOpencodeCommandPart[];
+} | {
+    kind: "sendPromptAsync";
+    sessionId: string;
+    messageId: string;
+    parts: BindingOpencodeCommandPart[];
+} | {
+    kind: "awaitPromptResponse";
+    sessionId: string;
+    messageId: string;
+} | {
+    kind: "readMessage";
+    sessionId: string;
+    messageId: string;
+} | {
+    kind: "listMessages";
+    sessionId: string;
+};
+export type BindingOpencodeCommandResult = {
+    kind: "lookupSession";
+    sessionId: string;
+    found: boolean;
+} | {
+    kind: "createSession";
+    sessionId: string;
+} | {
+    kind: "waitUntilIdle";
+    sessionId: string;
+} | {
+    kind: "appendPrompt";
+    sessionId: string;
+} | {
+    kind: "sendPromptAsync";
+    sessionId: string;
+} | {
+    kind: "awaitPromptResponse";
+    sessionId: string;
+    messageId: string;
+    parts: BindingOpencodeMessagePart[];
+} | {
+    kind: "readMessage";
+    sessionId: string;
+    messageId: string;
+    parts: BindingOpencodeMessagePart[];
+} | {
+    kind: "listMessages";
+    sessionId: string;
+    messages: BindingOpencodeMessage[];
+} | {
+    kind: "error";
+    commandKind: string;
+    sessionId: string | null;
+    code: "missingSession" | "unknown";
+    message: string;
+};
+export type BindingOpencodeCommandPart = {
+    kind: "text";
+    partId: string;
+    text: string;
+} | {
+    kind: "file";
+    partId: string;
+    mimeType: string;
+    fileName: string | null;
+    localPath: string;
+};
+export type BindingOpencodeDriverStep = {
+    kind: "command";
+    command: BindingOpencodeCommand;
+} | {
+    kind: "complete";
+    sessionId: string;
+    responseText: string;
+    finalText: string | null;
+} | {
+    kind: "failed";
+    message: string;
+};
+export type OpencodeExecutionDriver = {
+    start(): BindingOpencodeDriverStep;
+    resume(result: BindingOpencodeCommandResult): BindingOpencodeDriverStep;
+    observeEvent(observation: BindingExecutionObservation, nowMs: number): BindingProgressiveDirective;
+    free?(): void;
+};

package/dist/binding/opencode.js

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

package/dist/cli/args.d.ts

@@ -0,0 +1,9 @@
+export type CliCommand = {
+    kind: "help";
+} | {
+    kind: "init" | "doctor";
+    managed: boolean;
+    configDir: string | null;
+};
+export declare function parseCliCommand(argv: string[]): CliCommand;
+export declare function formatCliHelp(): string;

package/dist/cli/args.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+export function parseCliCommand(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        return { kind: "help" };
+    }
+    if (command !== "init" && command !== "doctor") {
+        throw new Error(`unknown command: ${command}`);
+    }
+    let managed = false;
+    let configDir = null;
+    for (let index = 0; index < rest.length; index += 1) {
+        const argument = rest[index];
+        if (argument === "--managed") {
+            managed = true;
+            continue;
+        }
+        if (argument === "--config-dir") {
+            const value = rest[index + 1];
+            if (!value) {
+                throw new Error("--config-dir requires a value");
+            }
+            configDir = resolve(value);
+            index += 1;
+            continue;
+        }
+        if (argument === "--help" || argument === "-h") {
+            return { kind: "help" };
+        }
+        throw new Error(`unknown argument: ${argument}`);
+    }
+    if (managed && configDir !== null) {
+        throw new Error("--managed cannot be combined with --config-dir");
+    }
+    return {
+        kind: command,
+        managed,
+        configDir,
+    };
+}
+export function formatCliHelp() {
+    return [
+        "opencode-gateway",
+        "",
+        "Commands:",
+        "  opencode-gateway init [--managed] [--config-dir <path>]",
+        "  opencode-gateway doctor [--managed] [--config-dir <path>]",
+        "",
+        "Defaults:",
+        "  init/doctor use OPENCODE_CONFIG_DIR when set, otherwise ~/.config/opencode",
+        "  --managed uses ~/.config/opencode-gateway/opencode",
+    ].join("\n");
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,6 @@
+type DoctorOptions = {
+    managed: boolean;
+    configDir: string | null;
+};
+export declare function runDoctor(options: DoctorOptions, env: Record<string, string | undefined>): Promise<void>;
+export {};

package/dist/cli/doctor.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { GATEWAY_CONFIG_FILE, OPENCODE_CONFIG_FILE } 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 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 config override: ${gatewayOverride ?? "not set"}`);
+    console.log(`  plugin configured: ${opencodeStatus.pluginConfigured}`);
+    console.log(`  TELEGRAM_BOT_TOKEN: ${env.TELEGRAM_BOT_TOKEN?.trim() ? "set" : "missing"}`);
+    if (opencodeStatus.error !== null) {
+        console.log(`  opencode config error: ${opencodeStatus.error}`);
+    }
+}
+async function describePath(path) {
+    return (await pathExists(path)) ? `present at ${path}` : `missing at ${path}`;
+}
+async function inspectOpencodeConfig(path) {
+    if (!(await pathExists(path))) {
+        return {
+            pluginConfigured: "no",
+            error: null,
+        };
+    }
+    try {
+        const parsed = parseOpencodeConfig(await readFile(path, "utf8"), path);
+        const plugins = parsed.plugin;
+        if (plugins === undefined) {
+            return {
+                pluginConfigured: "no",
+                error: null,
+            };
+        }
+        if (!Array.isArray(plugins)) {
+            return {
+                pluginConfigured: "invalid",
+                error: "`plugin` is not an array",
+            };
+        }
+        return {
+            pluginConfigured: plugins.some((entry) => entry === "opencode-gateway") ? "yes" : "no",
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            pluginConfigured: "unknown",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,6 @@
+type InitOptions = {
+    managed: boolean;
+    configDir: string | null;
+};
+export declare function runInit(options: InitOptions, env: Record<string, string | undefined>): Promise<void>;
+export {};

package/dist/cli/init.js

@@ -0,0 +1,35 @@
+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 { createDefaultOpencodeConfig, ensureGatewayPlugin, parseOpencodeConfig, stringifyOpencodeConfig, } from "./opencode-config";
+import { pathExists, resolveCliConfigDir } from "./paths";
+import { buildGatewayConfigTemplate } from "./templates";
+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);
+    await mkdir(configDir, { recursive: true });
+    let opencodeStatus = "already present";
+    if (!(await pathExists(opencodeConfigPath))) {
+        await writeFile(opencodeConfigPath, stringifyOpencodeConfig(createDefaultOpencodeConfig(options.managed)));
+        opencodeStatus = "created";
+    }
+    else {
+        const source = await readFile(opencodeConfigPath, "utf8");
+        const parsed = parseOpencodeConfig(source, opencodeConfigPath);
+        const next = ensureGatewayPlugin(parsed);
+        if (next.changed) {
+            await writeFile(opencodeConfigPath, stringifyOpencodeConfig(next.document));
+            opencodeStatus = "updated";
+        }
+    }
+    let gatewayStatus = "already present";
+    if (!(await pathExists(gatewayConfigPath))) {
+        await mkdir(dirname(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})`);
+}

package/dist/cli/opencode-config.d.ts

@@ -0,0 +1,10 @@
+type OpencodeConfigDocument = Record<string, unknown>;
+export type EnsurePluginResult = {
+    changed: boolean;
+    document: OpencodeConfigDocument;
+};
+export declare function createDefaultOpencodeConfig(managed: boolean): OpencodeConfigDocument;
+export declare function ensureGatewayPlugin(document: OpencodeConfigDocument): EnsurePluginResult;
+export declare function parseOpencodeConfig(source: string, path: string): OpencodeConfigDocument;
+export declare function stringifyOpencodeConfig(document: OpencodeConfigDocument): string;
+export {};

package/dist/cli/opencode-config.js

@@ -0,0 +1,62 @@
+const OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
+const PACKAGE_NAME = "opencode-gateway";
+export function createDefaultOpencodeConfig(managed) {
+    const document = {
+        $schema: OPENCODE_SCHEMA_URL,
+        plugin: [PACKAGE_NAME],
+    };
+    if (managed) {
+        document.server = {
+            hostname: "127.0.0.1",
+            port: 4096,
+        };
+    }
+    return document;
+}
+export function ensureGatewayPlugin(document) {
+    const plugins = document.plugin;
+    if (plugins === undefined) {
+        return {
+            changed: true,
+            document: {
+                ...document,
+                plugin: [PACKAGE_NAME],
+            },
+        };
+    }
+    if (!Array.isArray(plugins)) {
+        throw new Error("opencode.json field `plugin` must be an array when present");
+    }
+    if (plugins.some((entry) => entry === PACKAGE_NAME)) {
+        return {
+            changed: false,
+            document,
+        };
+    }
+    return {
+        changed: true,
+        document: {
+            ...document,
+            plugin: [...plugins, PACKAGE_NAME],
+        },
+    };
+}
+export function parseOpencodeConfig(source, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`failed to parse opencode config ${path}: ${formatError(error)}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`opencode config ${path} must decode to a JSON object`);
+    }
+    return parsed;
+}
+export function stringifyOpencodeConfig(document) {
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli/paths.d.ts

@@ -0,0 +1,7 @@
+type CliPathOptions = {
+    managed: boolean;
+    configDir: string | null;
+};
+export declare function resolveCliConfigDir(options: CliPathOptions, env: Record<string, string | undefined>): string;
+export declare function pathExists(path: string): Promise<boolean>;
+export {};

package/dist/cli/paths.js

@@ -0,0 +1,22 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { resolveManagedOpencodeConfigDir, resolveOpencodeConfigDir } from "../config/paths";
+export function resolveCliConfigDir(options, env) {
+    if (options.configDir !== null) {
+        return resolve(options.configDir);
+    }
+    if (options.managed) {
+        return resolveManagedOpencodeConfigDir(env);
+    }
+    return resolveOpencodeConfigDir(env);
+}
+export async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/templates.d.ts

@@ -0,0 +1 @@
+export declare function buildGatewayConfigTemplate(stateDbPath: string): string;

package/dist/cli/templates.js

@@ -0,0 +1,26 @@
+export function buildGatewayConfigTemplate(stateDbPath) {
+    return [
+        "# Opencode Gateway configuration",
+        "# Fill in secrets and provider details before enabling real integrations.",
+        "",
+        "[gateway]",
+        `state_db = "${escapeTomlString(stateDbPath)}"`,
+        "",
+        "[cron]",
+        "enabled = true",
+        "tick_seconds = 5",
+        "max_concurrent_runs = 1",
+        '# timezone = "Asia/Shanghai"',
+        "",
+        "[channels.telegram]",
+        "enabled = false",
+        'bot_token_env = "TELEGRAM_BOT_TOKEN"',
+        "poll_timeout_seconds = 25",
+        "allowed_chats = []",
+        "allowed_users = []",
+        "",
+    ].join("\n");
+}
+function escapeTomlString(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};