@jack200714/mafw 4.5.1

package/gateway/dist/runtime/loader.js

@@ -0,0 +1,240 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimePluginLoader = void 0;
+exports.createRuntimePluginContext = createRuntimePluginContext;
+/**
+ * Runtime 插件加载器 —— 扫描 ~/.mafw/runtime-plugins/*.js，校验契约形状，
+ * fail-open（单个文件失败不影响其他插件与内置 opencode）。
+ *
+ * 模板复用 MediaPluginLoader。支持 POST /api/runtime/reload 重扫插件文件
+ * （清 require.cache 后重新 require）。运行时热切换由 runtime-switch.ts
+ * 的 POST /api/runtime/switch 处理（进程内重建 + 事件流重订阅，无需重启）。
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+const config_1 = require("../config");
+const contract_1 = require("./contract");
+class RuntimePluginLoader {
+    pluginsDir;
+    factories = new Map();
+    meta = new Map();
+    state = new Map();
+    builtins = new Map();
+    constructor(pluginsDir) {
+        this.pluginsDir = pluginsDir;
+    }
+    /** 注册内置插件（优先级低于文件插件）。 */
+    registerBuiltin(name, factory, capabilities, external) {
+        this.builtins.set(name, { factory, capabilities, external });
+    }
+    async init() {
+        this.ensureDir();
+        await this.scan();
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.pluginsDir)) {
+            fs.mkdirSync(this.pluginsDir, { recursive: true });
+            fs.writeFileSync(path.join(this.pluginsDir, 'README.md'), README_CONTENT);
+            fs.writeFileSync(path.join(this.pluginsDir, 'example.js.disabled'), EXAMPLE_CONTENT);
+            logger_1.log.info(`[RuntimePluginLoader] Created ${this.pluginsDir}`);
+        }
+    }
+    async scan() {
+        if (!fs.existsSync(this.pluginsDir))
+            return;
+        const files = fs.readdirSync(this.pluginsDir).filter(f => f.endsWith('.js'));
+        const seen = new Set();
+        const loadedNames = new Set();
+        for (const file of files.sort()) {
+            await this.loadFile(file, loadedNames);
+            seen.add(file);
+        }
+        for (const [file] of this.state) {
+            if (!seen.has(file)) {
+                const prev = this.state.get(file);
+                if (prev?.name) {
+                    this.factories.delete(prev.name);
+                    this.meta.delete(prev.name);
+                }
+                this.state.delete(file);
+            }
+        }
+    }
+    async loadFile(file, loadedNames) {
+        const fullPath = path.join(this.pluginsDir, file);
+        try {
+            const cacheKey = require.resolve(fullPath);
+            delete require.cache[cacheKey];
+        }
+        catch { /* first load */ }
+        try {
+            const mod = require(fullPath);
+            const name = mod?.name;
+            if (!name || typeof name !== 'string') {
+                this.state.set(file, { file, status: 'error', error: 'missing name' });
+                return;
+            }
+            if (typeof mod.createRuntime !== 'function') {
+                this.state.set(file, { file, name, status: 'error', error: 'missing createRuntime(ctx)' });
+                return;
+            }
+            if (loadedNames.has(name)) {
+                this.state.set(file, { file, name, status: 'error', error: 'duplicate name' });
+                logger_1.log.warn(`[RuntimePluginLoader] ${file}: duplicate name '${name}', skipping`);
+                return;
+            }
+            // 能力合并：插件声明覆盖在 Tier-0 基线之上
+            const capabilities = { ...(0, contract_1.minimalCapabilities)(), ...(mod.capabilities || {}) };
+            // 插件 runtime 一律视为外部托管（gateway 不 spawn/监管其进程）
+            const external = mod.external !== false;
+            this.factories.set(name, mod.createRuntime);
+            this.meta.set(name, { capabilities, external });
+            this.state.set(file, { file, name, status: 'ok', capabilities });
+            loadedNames.add(name);
+            logger_1.log.info(`[RuntimePluginLoader] Loaded ${file} (${name})`);
+        }
+        catch (err) {
+            const prev = this.state.get(file);
+            this.state.set(file, { file, name: prev?.name, status: 'error', error: err.message });
+            logger_1.log.warn(`[RuntimePluginLoader] ${file} load error: ${err.message}`);
+        }
+    }
+    /** 插件不存在或未通过校验时返回 undefined（调用方回退内置 opencode）。文件插件优先于内置。 */
+    get(name) {
+        const createRuntime = this.factories.get(name);
+        const meta = this.meta.get(name);
+        if (createRuntime && meta)
+            return { createRuntime, ...meta };
+        const builtin = this.builtins.get(name);
+        if (builtin)
+            return { createRuntime: builtin.factory, ...builtin };
+        return undefined;
+    }
+    getState() {
+        for (const [name, b] of this.builtins) {
+            this.state.set(`builtin:${name}`, { file: `builtin:${name}`, name, status: 'ok', capabilities: b.capabilities });
+        }
+        return [...this.state.values()];
+    }
+}
+exports.RuntimePluginLoader = RuntimePluginLoader;
+function createRuntimePluginContext(credentials) {
+    return {
+        fetch: (url, opts) => fetch(url, { ...opts, signal: opts?.signal ?? AbortSignal.timeout(60000) }),
+        log: logger_1.log,
+        pluginConfig: (name) => config_1.config.raw?.runtime?.pluginConfig?.[name] ?? {},
+        credentials,
+    };
+}
+const README_CONTENT = `# Runtime Plugins
+
+Place \`.js\` files here to plug a new agent runtime into the MAFW gateway.
+Activate with config.yaml:
+
+\`\`\`yaml
+runtime:
+  plugin: my-runtime        # matches module.exports.name
+  pluginConfig: {}          # per-plugin config, read via ctx.pluginConfig(name)
+\`\`\`
+
+Or env: \`MAFW_RUNTIME_PLUGIN=my-runtime\`. Unknown/failed plugins fall back
+to the builtin opencode runtime (fail-open).
+
+## Plugin shape (CJS)
+
+\`\`\`js
+module.exports = {
+  name: "my-runtime",
+  // merged over Tier-0 defaults (sessionApi + promptWhileBusy already true)
+  capabilities: {
+    eventStream: false,
+    nativeApprovals: false,
+    providerConfigApi: false,
+    perLlmCallTransform: false,
+    // optional (not in tier hierarchy):
+    sessionStorageApi: false,  // direct session storage access
+    agentConfigApi: false,     // agent definition installation
+  },
+  external: true,             // gateway never spawns plugin runtime processes
+  async createRuntime(ctx) {
+    // ctx.fetch / ctx.log / ctx.pluginConfig(name) / ctx.apiKey(name)
+    return {
+      name: "my-runtime",
+      capabilities: { /* same object as above */ },
+      session: {
+        async create(opts) { /* {directory?} → {id} */ },
+        async promptAsync(opts) { /* {sessionID, parts|message, ...} → void */ },
+        async prompt(opts) { /* → {parts, ...} */ },
+        async messages(opts) { /* {sessionID, limit?, before?} → {data, nextCursor?} */ },
+        async get({ sessionID }) {},
+        async delete({ sessionID }) {},
+        async abort({ sessionID }) {},
+        async list(opts) { return []; },
+        async todo({ sessionID }) { return []; },
+        async children({ sessionID }) { return []; },
+        async summarize(opts) {},
+        // optional (requires sessionStorageApi capability):
+        // async listByDirectory(directory, limit) { return []; },
+      },
+      global: { async event() { /* → {stream: AsyncIterable} */ } },
+      provider: { async list() { return { all: [], connected: [], default: {} }; } },
+      app: { async agents() { return []; } },
+      config: { async get() { return {}; }, async update(c) { return c; } },
+      getBaseUrl() { return "http://127.0.0.1:4096"; },
+      async healthCheck() { return true; },
+      // optional:
+      // credentials: { getApiKey(provider) { return null; } },
+      // agents: { async install(name, definition) {}, async remove(name) {} },
+    };
+  },
+};
+\`\`\`
+
+Capabilities declared here gate gateway features declaratively: missing
+capabilities disable the corresponding features (503 on gated endpoints,
+skipped event subscription) — they never crash.
+`;
+const EXAMPLE_CONTENT = `// Rename to example.js to activate
+module.exports = {
+  name: "example",
+  capabilities: { eventStream: false },
+  async createRuntime(ctx) {
+    ctx.log.info("[example-runtime] created");
+    throw new Error("example plugin: implement createRuntime before activating");
+  },
+};
+`;

package/gateway/dist/runtime/normalize.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOpencodeEvent = normalizeOpencodeEvent;
+/**
+ * 事件归一化器 —— 把 runtime 原生事件翻译成 EventFacets（正交切面）。
+ *
+ * 每个 runtime 一个 normalize 函数；index.ts 的调度逻辑只消费 facets，
+ * 不再出现 runtime 事件类型字符串。opencode 版本知识（≥1.18 无
+ * session.next.step.ended，step 以 step-finish part 结算）只存在于本文件
+ * 和 step-inject.ts 的两个 helper 里。
+ *
+ * 注意：facets 是正交的（一个事件可同时有 step 与 chatSignal），这是为了
+ * 与现 handleOpencodeEvent 的多路消费行为逐点等价。
+ */
+const step_inject_1 = require("../recall/step-inject");
+function normalizeOpencodeEvent(evt) {
+    const payload = evt?.payload || {};
+    const type = payload?.type || evt?.type || '';
+    const props = payload?.properties || evt?.properties || {};
+    const sessionID = props?.sessionID || props?.part?.sessionID || props?.info?.sessionID || payload?.sessionID || evt?.sessionID;
+    // settled-step 归一化：legacy step.ended（保留兜底）→ step-finish part →
+    // completed assistant message，与现 handleOpencodeEvent 的判定顺序一致。
+    let step = null;
+    if (type === 'session.next.step.ended' && sessionID) {
+        step = { sessionID, assistantMessageID: props?.assistantMessageID, finish: props?.finish };
+    }
+    else if (type === 'message.part.updated') {
+        step = (0, step_inject_1.stepPropsFromPartUpdated)(props);
+    }
+    else if (type === 'message.updated') {
+        step = (0, step_inject_1.stepPropsFromMessageUpdated)(props);
+    }
+    let chatSignal = null;
+    let deltaText;
+    let chatError;
+    if (type === 'message.part.updated') {
+        const text = props?.part?.text || props?.delta || '';
+        if (text) {
+            deltaText = text;
+            chatSignal = 'delta';
+        }
+    }
+    else if (type === 'session.idle' || type === 'message.updated') {
+        chatSignal = 'complete';
+    }
+    else if (type === 'session.error' || type === 'message.error') {
+        chatSignal = 'error';
+        chatError = props?.error || 'Unknown error';
+    }
+    const broadcast = type === 'session.idle' ? 'idle' : type === 'session.error' ? 'error' : 'passthrough';
+    // 自更新调用者定位：仅工具事件携带 command 时提取。
+    // （'session.next.tool' 已包含 'tool' 子串，includes('tool') 一条即覆盖，
+    //  与现 `(type.includes('tool') || type.includes('session.next.tool'))` 等价。）
+    const toolArgs = props?.args || props?.info?.args || payload?.args;
+    const command = typeof toolArgs?.command === 'string' ? toolArgs.command : '';
+    const toolCommand = command && type.includes('tool') ? command : undefined;
+    const compaction = type === 'session.compacting' ? 'start' : type === 'session.compacted' ? 'end' : null;
+    return { type, properties: props, sessionID, directory: evt?.directory, step, chatSignal, deltaText, chatError, broadcast, compaction, toolCommand };
+}

package/gateway/dist/runtime/opencode-runtime.js

@@ -0,0 +1,336 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProviderApiKey = exports.readOpencodeAuth = exports.DEFAULT_AUTH_PATH = void 0;
+exports.opencodeDbPath = opencodeDbPath;
+exports.serializeAgentToFrontmatter = serializeAgentToFrontmatter;
+exports.installAgentFile = installAgentFile;
+exports.createOpencodeRuntime = createOpencodeRuntime;
+/**
+ * 内置 opencode runtime —— 契约的"恒等实现"：能力全满（Tier 2），
+ * 其事件/消息形状即归一化的目标形状。新 runtime 插件以本文件为参照。
+ *
+ * credentials: 从 opencode auth.json 读取 provider API key（与 plugin ctx
+ * 的 apiKey(name) 语义对齐）。其他 runtime 可提供自己的 credential source。
+ *
+ * sessionStorageApi: opencode 的会话数据持久化在 SQLite（opencode.db），
+ * serve 的 session.list 按 project_id = "global" 解析，会隐藏真正属于
+ * 某个项目目录的会话。listByDirectory 直读 SQLite 解决此问题；其他
+ * runtime 若无等价存储则声明 sessionStorageApi: false，gateway 回退到
+ * session.list + 客户端目录过滤。
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const contract_1 = require("./contract");
+const serve_sidecar_1 = require("./serve-sidecar");
+const opencode_adapter_1 = require("../opencode-adapter");
+const config_1 = require("../config");
+const auth_1 = require("./auth");
+const completion_http_1 = require("./completion-http");
+const logger_1 = require("../core/utils/logger");
+// Re-export auth utilities for consumers (single implementation source)
+var auth_2 = require("./auth");
+Object.defineProperty(exports, "DEFAULT_AUTH_PATH", { enumerable: true, get: function () { return auth_2.DEFAULT_AUTH_PATH; } });
+Object.defineProperty(exports, "readOpencodeAuth", { enumerable: true, get: function () { return auth_2.readOpencodeAuth; } });
+Object.defineProperty(exports, "getProviderApiKey", { enumerable: true, get: function () { return auth_2.getProviderApiKey; } });
+// ─── SQLite 直读层（opencode.db） ────────────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { DatabaseSync } = require('node:sqlite');
+function normalizeDir(dir) {
+    return dir.replace(/\\/g, '/').toLowerCase().replace(/\/+$/, '');
+}
+function opencodeDbPath() {
+    const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+    return path.join(base, 'opencode', 'opencode.db');
+}
+function toSessionShape(row) {
+    return {
+        id: row.id,
+        projectID: row.project_id,
+        directory: row.directory,
+        title: row.title,
+        parentID: row.parent_id ?? undefined,
+        metadata: row.metadata ?? undefined,
+        time: { created: row.time_created, updated: row.time_updated },
+    };
+}
+function projectIdsForDirectory(db, directory) {
+    const target = normalizeDir(directory);
+    const ids = new Set();
+    try {
+        const byDir = db.prepare('SELECT project_id, directory FROM project_directory').all();
+        for (const row of byDir) {
+            const rowDir = row.directory;
+            if (typeof rowDir === 'string' && normalizeDir(rowDir) === target) {
+                ids.add(String(row.project_id));
+            }
+        }
+    }
+    catch { /* column may be absent on old schemas */ }
+    try {
+        const byWorktree = db.prepare('SELECT id, worktree FROM project').all();
+        for (const row of byWorktree) {
+            const rowDir = row.worktree;
+            if (typeof rowDir === 'string' && normalizeDir(rowDir) === target) {
+                ids.add(String(row.id));
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return [...ids];
+}
+function sessionsUnderDirectory(db, directory, limit = 200) {
+    const target = normalizeDir(directory);
+    const rows = db.prepare(`SELECT id, project_id, parent_id, directory, title, metadata, time_created, time_updated
+     FROM session
+     ORDER BY time_updated DESC
+     LIMIT 5000`).all();
+    const matching = [];
+    for (const row of rows) {
+        const rowDir = normalizeDir(row.directory || '');
+        if (rowDir === target || rowDir.startsWith(target + '/'))
+            matching.push(row);
+        if (matching.length >= limit)
+            break;
+    }
+    return matching;
+}
+function listSessionsFromDb(directory, limit = 200) {
+    if (!directory)
+        return [];
+    const dbPath = opencodeDbPath();
+    if (!fs.existsSync(dbPath))
+        return [];
+    let db;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+    }
+    catch {
+        return [];
+    }
+    try {
+        const projectIds = projectIdsForDirectory(db, directory);
+        const out = [];
+        const seen = new Set();
+        const push = (row) => {
+            if (seen.has(row.id))
+                return;
+            seen.add(row.id);
+            out.push(toSessionShape(row));
+        };
+        if (projectIds.length > 0) {
+            const placeholders = projectIds.map(() => '?').join(', ');
+            const rows = db.prepare(`SELECT id, project_id, parent_id, directory, title, metadata, time_created, time_updated
+         FROM session
+         WHERE project_id IN (${placeholders})
+         ORDER BY time_updated DESC
+         LIMIT ?`).all(...projectIds, limit);
+            for (const row of rows)
+                push(row);
+        }
+        if (out.length === 0) {
+            for (const row of sessionsUnderDirectory(db, directory, limit))
+                push(row);
+        }
+        return out;
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+// ─── Agent 定义序列化（AgentDefinition → opencode frontmatter） ─────────────
+const OPENCODE_BUILTIN_PERM_KEYS = new Set(['question', 'plan_exit']);
+function serializeAgentToFrontmatter(def) {
+    const lines = ['---'];
+    if (def.mode)
+        lines.push(`mode: ${def.mode}`);
+    lines.push(`description: ${def.description}`);
+    if (def.color)
+        lines.push(`color: "${def.color}"`);
+    if (def.model)
+        lines.push(`model: ${def.model}`);
+    if (def.temperature !== undefined)
+        lines.push(`temperature: ${def.temperature}`);
+    const permLines = [];
+    const tools = def.permissions.tools ?? {};
+    const deferredTools = [];
+    for (const [key, rule] of Object.entries(tools)) {
+        if (OPENCODE_BUILTIN_PERM_KEYS.has(key)) {
+            permLines.push(`  ${key}: ${rule}`);
+        }
+        else {
+            deferredTools.push([key, rule]);
+        }
+    }
+    if (def.permissions.task) {
+        permLines.push('  task:');
+        for (const [key, rule] of Object.entries(def.permissions.task)) {
+            permLines.push(`    ${key}: ${rule}`);
+        }
+    }
+    if (def.permissions.edit) {
+        permLines.push('  edit:');
+        permLines.push(`    "*": ${def.permissions.edit}`);
+    }
+    if (def.permissions.bash) {
+        permLines.push(`  bash: ${def.permissions.bash}`);
+    }
+    for (const [key, rule] of deferredTools) {
+        permLines.push(`  ${key}: ${rule}`);
+    }
+    if (def.tools) {
+        lines.push('tools:');
+        for (const [tool, enabled] of Object.entries(def.tools)) {
+            lines.push(`  '${tool}': ${enabled}`);
+        }
+    }
+    if (permLines.length > 0) {
+        lines.push('permission:');
+        lines.push(...permLines);
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push(def.systemPrompt);
+    lines.push('');
+    return lines.join('\n');
+}
+function installAgentFile(name, def, baseDir) {
+    const dir = baseDir;
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${name}.md`);
+    const content = serializeAgentToFrontmatter(def);
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+}
+function opencodeAgentDir() {
+    return path.join(os.homedir(), '.config', 'opencode', 'agent');
+}
+async function createOpencodeRuntime(config) {
+    const client = await (0, opencode_adapter_1.createOpencodeAdapter)(config);
+    const isExternal = !!process.env.MAFW_SERVER_SERVE_URL;
+    const caps = (0, contract_1.fullCapabilities)();
+    if (isExternal) {
+        // External runtimes only probe; they don't manage the serve process.
+        caps.agentProcessApi = false;
+    }
+    const rt = Object.assign(client, {
+        name: 'opencode',
+        capabilities: caps,
+        external: isExternal,
+        credentials: {
+            getApiKey(provider) {
+                return (0, auth_1.getProviderApiKey)(provider) ?? null;
+            },
+        },
+        getBaseUrl() {
+            return process.env.MAFW_SERVER_SERVE_URL || config_1.config.server.serveUrl;
+        },
+        async healthCheck() {
+            try {
+                const res = await fetch(`${config.baseUrl}/global/health`, {
+                    headers: config.headers,
+                    signal: AbortSignal.timeout(3000),
+                });
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+    rt.session.listByDirectory = async (directory, limit) => {
+        return listSessionsFromDb(directory, limit);
+    };
+    rt.agents = {
+        async install(name, definition) {
+            const dir = opencodeAgentDir();
+            const existed = fs.existsSync(path.join(dir, `${name}.md`));
+            const filePath = installAgentFile(name, definition, dir);
+            logger_1.log.info(`[ManagerAgent] ${existed ? 'updated' : 'wrote'} ${filePath}`);
+        },
+    };
+    // completionApi: stateless single-shot completion over the shared direct-HTTP
+    // transport. Endpoint/key resolution mirrors index-scan's chain (opencode
+    // provider config options → auth.json), so any OpenAI-compatible provider
+    // connected in opencode works out of the box.
+    rt.completion = {
+        async complete(req) {
+            return (0, completion_http_1.httpComplete)(req, {
+                scanEndpoints: config_1.config.recall?.scanEndpoints || undefined,
+                resolveEndpoint: async (providerID) => {
+                    try {
+                        const cfg = await client.config.get();
+                        const base = cfg?.provider?.[providerID]?.options?.baseURL;
+                        if (typeof base === 'string' && base)
+                            return `${base.replace(/\/+$/, '')}/chat/completions`;
+                    }
+                    catch { /* fail-open to the next resolution step */ }
+                    return null;
+                },
+                resolveApiKey: async (providerID) => {
+                    try {
+                        const viaAuth = (0, auth_1.getProviderApiKey)(providerID);
+                        if (viaAuth)
+                            return viaAuth;
+                        const cfg = await client.config.get();
+                        const key = cfg?.provider?.[providerID]?.options?.apiKey;
+                        if (typeof key === 'string' && key)
+                            return key;
+                    }
+                    catch { /* fail-open to the next resolution step */ }
+                    return null;
+                },
+            });
+        },
+    };
+    // agentProcess: owned runtimes provide BOTH primitives themselves —
+    // spawnServe (windowsHide-safe `opencode serve` sidecar) and restart (kill
+    // the serve port; gateway orchestrates the respawn + event resubscribe).
+    // Gateway core never hardcodes agent-specific spawn details.
+    if (!rt.external) {
+        rt.agentProcess = {
+            spawnServe: (opts) => (0, serve_sidecar_1.startServeSidecar)(opts),
+            async restart() {
+                logger_1.log.info('[Runtime] agentProcess.restart() — killing serve (gateway orchestrates respawn)');
+                (0, serve_sidecar_1.killServePort)(config_1.config.server.servePort);
+            },
+        };
+    }
+    return rt;
+}