opencode-gateway 0.1.0 → 0.2.0

package/dist/memory/prompt.js

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import { extname, relative } from "node:path";
+const MARKDOWN_GLOBS = ["**/*.md", "**/*.markdown"];
+const UTF8_TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+export class GatewayMemoryPromptProvider {
+    config;
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    async buildPrompt() {
+        if (this.config.entries.length === 0) {
+            return null;
+        }
+        const sections = await Promise.all(this.config.entries.map((entry) => this.buildEntrySection(entry)));
+        return ["Gateway memory:", ...sections].join("\n\n");
+    }
+    async buildEntrySection(entry) {
+        const lines = [`Configured path: ${entry.displayPath}`, `Description: ${entry.description}`];
+        const injectedFiles = await collectInjectedFiles(entry, this.logger);
+        for (const file of injectedFiles) {
+            lines.push("");
+            lines.push(`File: ${file.displayPath}`);
+            lines.push(codeFence(file.infoString, file.text));
+        }
+        return lines.join("\n");
+    }
+}
+async function collectInjectedFiles(entry, logger) {
+    if (entry.kind === "file") {
+        if (!entry.injectContent) {
+            return [];
+        }
+        const text = await readTextFile(entry.path, logger);
+        if (text === null) {
+            return [];
+        }
+        return [
+            {
+                displayPath: entry.displayPath,
+                infoString: inferFenceInfoString(entry.path),
+                text,
+            },
+        ];
+    }
+    const filePaths = new Set();
+    if (entry.injectMarkdownContents) {
+        for (const pattern of MARKDOWN_GLOBS) {
+            addMatchingFiles(filePaths, entry.path, pattern);
+        }
+    }
+    for (const pattern of entry.globs) {
+        addMatchingFiles(filePaths, entry.path, pattern);
+    }
+    const injectedFiles = [];
+    for (const filePath of [...filePaths].sort((left, right) => left.localeCompare(right))) {
+        const text = await readTextFile(filePath, logger);
+        if (text === null) {
+            continue;
+        }
+        injectedFiles.push({
+            displayPath: relativeDisplayPath(entry.path, entry.displayPath, filePath),
+            infoString: inferFenceInfoString(filePath),
+            text,
+        });
+    }
+    return injectedFiles;
+}
+function addMatchingFiles(result, cwd, pattern) {
+    const glob = new Bun.Glob(pattern);
+    for (const match of glob.scanSync({ cwd, absolute: true, onlyFiles: true })) {
+        result.add(match);
+    }
+}
+async function readTextFile(path, logger) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch (error) {
+        logger.log("warn", `memory file could not be read and will be skipped: ${path}: ${formatError(error)}`);
+        return null;
+    }
+    let text;
+    try {
+        text = UTF8_TEXT_DECODER.decode(bytes);
+    }
+    catch {
+        logger.log("warn", `memory file is not valid UTF-8 and will be skipped: ${path}`);
+        return null;
+    }
+    if (text.includes("\u0000")) {
+        logger.log("warn", `memory file looks binary and will be skipped: ${path}`);
+        return null;
+    }
+    return text;
+}
+function relativeDisplayPath(rootPath, rootDisplayPath, filePath) {
+    const suffix = relative(rootPath, filePath);
+    if (suffix.length === 0) {
+        return rootDisplayPath;
+    }
+    return `${rootDisplayPath}/${suffix.replaceAll("\\", "/")}`;
+}
+function inferFenceInfoString(path) {
+    const extension = extname(path).slice(1).toLowerCase();
+    if (!/^[a-z0-9_+-]+$/.test(extension)) {
+        return "";
+    }
+    return extension;
+}
+function codeFence(infoString, text) {
+    const language = infoString.length === 0 ? "" : infoString;
+    return [`\`\`\`${language}`, text, "```"].join("\n");
+}
+function formatError(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message;
+    }
+    return String(error);
+}

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,43 @@ 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 waitForSessionToSettle;
+    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,8 @@
+import { ConversationCoordinator } from "./conversation-coordinator";
 import { runOpencodeDriver } from "./opencode-runner";
+const SESSION_ABORT_SETTLE_TIMEOUT_MS = 5_000;
+const SESSION_ABORT_POLL_MS = 250;
+const SESSION_RESIDUAL_BUSY_GRACE_POLLS = 3;
 export class GatewayExecutor {
     module;
     store;
@@ -6,13 +10,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 +59,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 +89,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 +162,139 @@ 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.waitForSessionToSettle(sessionId, SESSION_RESIDUAL_BUSY_GRACE_POLLS)) {
+            return;
+        }
+        this.logger.log("debug", `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 waitForSessionToSettle(sessionId, extraPolls) {
+        for (let attempt = 0; attempt <= extraPolls; attempt += 1) {
+            if (!(await this.opencode.isSessionBusy(sessionId))) {
+                return true;
+            }
+            if (attempt < extraPolls) {
+                await Bun.sleep(SESSION_ABORT_POLL_MS);
+            }
+        }
+        return false;
+    }
+    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 +326,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 +369,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.d.ts

@@ -6,5 +6,5 @@ export declare class GatewaySessionContext {
     replaceReplyTargets(sessionId: string, conversationKey: string, targets: BindingDeliveryTarget[], recordedAtMs: number): void;
     listReplyTargets(sessionId: string): BindingDeliveryTarget[];
     getDefaultReplyTarget(sessionId: string): BindingDeliveryTarget | null;
-    buildSystemPrompt(sessionId: string): string | null;
+    isGatewaySession(sessionId: string): boolean;
 }