okengine 0.23.0 → 0.23.1

package/src/kernel/store-transaction.test.ts

@@ -0,0 +1,95 @@
+/**
+ * `fx.store().transaction` publishes signal emits only after commit.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { SqlConnection } from "../drivers/types.ts";
+import { memorySignalDriver } from "../drivers/signal-memory.ts";
+import { signal } from "../elements/signal.ts";
+import { store } from "../elements/store.ts";
+import { createSqlStoreHandle } from "../elements/store/sql-session.ts";
+import type { StoreRuntime } from "../elements/store/runtime.ts";
+import { createFxContext } from "./fx.ts";
+import type { SignalRuntime } from "../elements/signal/runtime.ts";
+
+function fakeSql(): SqlConnection {
+  return {
+    driverId: "memory",
+    role: "primary",
+    async query() {
+      return [];
+    },
+    async exec() {
+      return { changes: 1 };
+    },
+    async transaction(fn) {
+      return fn(this);
+    },
+    async close() {},
+  };
+}
+
+describe("fx.store().transaction", () => {
+  test("commit publishes the staged emit; rollback drops it", async () => {
+    const ping = signal.once("ping");
+    const signals = new Map([[ping.name, ping]]);
+    const bus = await memorySignalDriver.open({ signals });
+    const got: unknown[] = [];
+    await bus.subscribe("ping", "c", async (message) => {
+      got.push(message.payload);
+    });
+    const signalRuntime: SignalRuntime = {
+      driverId: "memory",
+      get bus() {
+        return bus;
+      },
+      declarations: signals,
+      register(decl) {
+        signals.set(decl.name, decl);
+      },
+      async start() {
+        return bus;
+      },
+      emit: (name, payload, options) => bus.emit(name, payload, options),
+      deadLetters: (name) => bus.deadLetters(name),
+      live: (name, opts) => bus.live(name, opts),
+      checkLiveResume: (name, afterId) => bus.checkLiveResume(name, afterId),
+      async close() {
+        await bus.close();
+      },
+    };
+    const notes = { name: "notes" };
+    const storeRuntime = {
+      async open() {
+        return createSqlStoreHandle("sql:db", {
+          connection: fakeSql(),
+          classifications: new Map(),
+          routedRole: "primary",
+        });
+      },
+    } as unknown as StoreRuntime;
+    const db = store.sql("db");
+    const { fx } = createFxContext({
+      flow: "notes.write",
+      effects: { writes: ["sql:notes", "sql:db"], emits: ["ping"] },
+      storeRuntime,
+      signalRuntime,
+    });
+
+    await fx.store(db).transaction(async (tx) => {
+      await tx.insert(notes).values({ id: "1" });
+      await fx.emit(ping, { id: "1" });
+    });
+    await bus.drain();
+    expect(got).toEqual([{ id: "1" }]);
+
+    await expect(
+      fx.store(db).transaction(async () => {
+        await fx.emit(ping, { id: "no" });
+        throw new Error("nope");
+      }),
+    ).rejects.toThrow("nope");
+    await bus.drain();
+    expect(got).toEqual([{ id: "1" }]);
+  });
+});

package/src/mcp/docs-server.ts

@@ -16,7 +16,9 @@ import { asData } from "./data.ts";
 import { defaultDocsContentDir, loadDocsIndex, type DocsIndex } from "./docs-index.ts";
 import { createDocsToolRuntime } from "./docs-tools.ts";
 import {
-  MCP_PROTOCOL_VERSION,
+  acceptsMcpProtocolVersion,
+  negotiateMcpProtocolVersion,
+  protocolVersionOf,
   parseJsonRpcRequest,
   parseToolsCallParams,
   rpcError,
@@ -94,10 +96,18 @@ export async function createDocsMcpServer(
 
     switch (rpc.method) {
       case "initialize": {
+        const requested = protocolVersionOf(rpc.params);
+        const protocolVersion = negotiateMcpProtocolVersion(requested);
+        if (protocolVersion === undefined) {
+          return jsonRpcHttp(
+            rpcError(id, RpcErrorCode.invalidParams, "unsupported protocol version"),
+            400,
+          );
+        }
         const sessionId = newMcpTransportSessionId();
         transportSessions.add(sessionId);
         const result: McpInitializeResult = {
-          protocolVersion: MCP_PROTOCOL_VERSION,
+          protocolVersion,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: "okengine-docs-mcp", version },
           sessionId,
@@ -124,6 +134,13 @@ export async function createDocsMcpServer(
         );
       }
       case "tools/call": {
+        const requested = protocolVersionOf(rpc.params);
+        if (requested !== undefined && !acceptsMcpProtocolVersion(requested)) {
+          return jsonRpcHttp(
+            rpcError(id, RpcErrorCode.invalidParams, "unsupported protocol version"),
+            400,
+          );
+        }
         const call = parseToolsCallParams(rpc.params);
         if (!call.ok) {
           return jsonRpcHttp(rpcError(id, RpcErrorCode.invalidParams, call.message), 400);

package/src/mcp/mcp.test.ts

@@ -15,6 +15,7 @@ import { asData, isDataEnvelope, MCP_DATA_KIND } from "./data.ts";
 import { authenticateMcpRequest, mintMcpSession, MCP_AUDIENCE } from "./session.ts";
 import { createMcpServer } from "./server.ts";
 import { createToolRuntime } from "./tools.ts";
+import { MCP_CLIENT_PROTOCOL_VERSION, MCP_PROTOCOL_VERSION } from "./versions.ts";
 
 const SECRET = "mcp-test-secret";
 
@@ -314,4 +315,86 @@ describe("MCP HTTP server", () => {
     expect(callBody.result.structuredContent.kind).toBe("data");
     expect(callBody.result.structuredContent.content.manifest.app).toBe("skyport");
   });
+
+  test("initialize advertises 2024-11-05 and rejects a version the server does not implement", async () => {
+    const store = createSessionStore();
+    const issued = await mintMcpSession({
+      store,
+      secret: SECRET,
+      principalId: "op1",
+      scopes: ["console:*"],
+    });
+    const server = createMcpServer({
+      sessions: store,
+      secret: SECRET,
+      context: {
+        getManifest: () => SAMPLE_MANIFEST,
+        listRuns: async () => [],
+      },
+    });
+    const headers = {
+      host: "127.0.0.1:6535",
+      authorization: `Bearer ${issued.accessToken}`,
+      "content-type": "application/json",
+    };
+    const init = await server.fetch(
+      new Request("http://127.0.0.1:6535/mcp", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: { protocolVersion: MCP_PROTOCOL_VERSION },
+        }),
+      }),
+    );
+    expect(init.status).toBe(200);
+    const initBody = (await init.json()) as { result: { protocolVersion: string } };
+    expect(initBody.result.protocolVersion).toBe("2024-11-05");
+    const omitted = await server.fetch(
+      new Request("http://127.0.0.1:6535/mcp", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 2,
+          method: "initialize",
+          params: {},
+        }),
+      }),
+    );
+    const omittedBody = (await omitted.json()) as { result: { protocolVersion: string } };
+    expect(omittedBody.result.protocolVersion).toBe("2024-11-05");
+    const rejected = await server.fetch(
+      new Request("http://127.0.0.1:6535/mcp", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 3,
+          method: "initialize",
+          params: { protocolVersion: MCP_CLIENT_PROTOCOL_VERSION },
+        }),
+      }),
+    );
+    expect(rejected.status).toBe(400);
+    const call = await server.fetch(
+      new Request("http://127.0.0.1:6535/mcp", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 4,
+          method: "tools/call",
+          params: {
+            name: "oke.manifest.get",
+            arguments: {},
+            protocolVersion: MCP_PROTOCOL_VERSION,
+          },
+        }),
+      }),
+    );
+    expect(call.status).toBe(200);
+  });
 });

package/src/mcp/protocol.ts

@@ -129,8 +129,14 @@ export interface McpInitializeResult {
   readonly sessionId: string;
 }
 
-/** Supported MCP protocol version. */
-export const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** Highest protocol version the servers implement (`2024-11-05`). */
+export {
+  MCP_PROTOCOL_VERSION,
+  MCP_SUPPORTED_PROTOCOL_VERSIONS,
+  acceptsMcpProtocolVersion,
+  negotiateMcpProtocolVersion,
+  protocolVersionOf,
+} from "./versions.ts";
 
 /**
  * Parse tools/call params.

package/src/mcp/server.ts

@@ -18,7 +18,9 @@ import { MCP_PORT, type ServerHandle } from "../runtime/types.ts";
 import { SessionError, type SessionStore } from "../auth/sessions.ts";
 import { asData } from "./data.ts";
 import {
-  MCP_PROTOCOL_VERSION,
+  acceptsMcpProtocolVersion,
+  negotiateMcpProtocolVersion,
+  protocolVersionOf,
   parseJsonRpcRequest,
   parseToolsCallParams,
   rpcError,
@@ -149,10 +151,20 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
 
     switch (rpc.method) {
       case "initialize": {
+        const requested = protocolVersionOf(rpc.params);
+        const protocolVersion = negotiateMcpProtocolVersion(requested);
+        if (protocolVersion === undefined) {
+          return respond(
+            jsonRpcHttp(
+              rpcError(id, RpcErrorCode.invalidParams, "unsupported protocol version"),
+              400,
+            ),
+          );
+        }
         const sessionId = newMcpTransportSessionId();
         transportSessions.add(sessionId);
         const result: McpInitializeResult = {
-          protocolVersion: MCP_PROTOCOL_VERSION,
+          protocolVersion,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: "okengine-mcp", version },
           sessionId,
@@ -182,6 +194,15 @@ export function createMcpServer(options: CreateMcpServerOptions): McpServer {
         );
       }
       case "tools/call": {
+        const requested = protocolVersionOf(rpc.params);
+        if (requested !== undefined && !acceptsMcpProtocolVersion(requested)) {
+          return respond(
+            jsonRpcHttp(
+              rpcError(id, RpcErrorCode.invalidParams, "unsupported protocol version"),
+              400,
+            ),
+          );
+        }
         const call = parseToolsCallParams(rpc.params);
         if (!call.ok) {
           return respond(jsonRpcHttp(rpcError(id, RpcErrorCode.invalidParams, call.message), 400));

package/src/mcp/versions.ts

@@ -0,0 +1,60 @@
+/**
+ * MCP protocol versions.
+ *
+ * The app and docs servers implement `initialize`, `ping`, `tools/list`, and
+ * `tools/call`. That is the 2024-11-05 tools surface, so they advertise
+ * {@link MCP_PROTOCOL_VERSION} and reject any other client version.
+ *
+ * The outbound client is separate. It probes external servers with
+ * {@link MCP_CLIENT_PROTOCOL_VERSION} (`_meta` on each request) and falls
+ * back to a 2024-11-05 `initialize`. That constant is not the server
+ * advertisement.
+ */
+
+/** Versions the app and docs servers implement, newest last. */
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05"] as const;
+
+/** Highest protocol version the servers implement and advertise. */
+export const MCP_PROTOCOL_VERSION: (typeof MCP_SUPPORTED_PROTOCOL_VERSIONS)[number] = "2024-11-05";
+
+/** Version the outbound MCP client probes first. Not the server advertisement. */
+export const MCP_CLIENT_PROTOCOL_VERSION = "2026-07-28";
+
+/** `initialize` dialect the outbound client falls back to. */
+export const MCP_LEGACY_PROTOCOL_VERSION = "2024-11-05";
+
+const ACCEPTED: readonly string[] = MCP_SUPPORTED_PROTOCOL_VERSIONS;
+
+/**
+ * Whether a client-offered protocol version is one this server implements.
+ *
+ * @param version - `initialize` or `tools/call` protocol version
+ */
+export function acceptsMcpProtocolVersion(version: string): boolean {
+  return ACCEPTED.includes(version);
+}
+
+/**
+ * Pick the protocol version for an `initialize` result.
+ *
+ * An omitted client version gets the highest version this server implements.
+ * A supported client version is echoed. Anything else has no overlap.
+ *
+ * @param requested - Client `protocolVersion`, when present
+ */
+export function negotiateMcpProtocolVersion(requested: string | undefined): string | undefined {
+  if (requested === undefined) return MCP_PROTOCOL_VERSION;
+  if (acceptsMcpProtocolVersion(requested)) return requested;
+  return undefined;
+}
+
+/**
+ * Read `params.protocolVersion` when the client sent one.
+ *
+ * @param params - JSON-RPC params
+ */
+export function protocolVersionOf(params: unknown): string | undefined {
+  if (params === null || typeof params !== "object" || Array.isArray(params)) return undefined;
+  const version = (params as { protocolVersion?: unknown }).protocolVersion;
+  return typeof version === "string" && version.length > 0 ? version : undefined;
+}

package/src/plugins/index.ts

@@ -24,6 +24,7 @@ export {
   type MagicLinkOptions,
 } from "./magic-link.ts";
 export { maintenanceMode, type MaintenanceModeOptions } from "./maintenance-mode.ts";
+export { mena, menaChannels, type MenaChannelOptions } from "./mena.ts";
 export {
   createPhoneStore,
   otp,

package/src/plugins/mena.ts

@@ -0,0 +1,56 @@
+/**
+ * MENA channel plugin — Taqnyat, Unifonic, and Msegat behind one plugin.
+ *
+ * Drivers stay the protocol adapters. `fx.sendOtp`, `fx.verifyOtp`, and
+ * `fx.deliverOtp` remain supported Channel methods.
+ */
+
+import { openMsegatChannel } from "../drivers/channel-msegat.ts";
+import { openTaqnyatChannel } from "../drivers/channel-taqnyat.ts";
+import { openTaqnyatMailChannel } from "../drivers/channel-taqnyat-mail.ts";
+import { openTaqnyatWhatsAppChannel } from "../drivers/channel-taqnyat-whatsapp.ts";
+import { openUnifonicChannel } from "../drivers/channel-unifonic.ts";
+import type { ChannelDriver, ChannelOpenOptions } from "../drivers/channel-types.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+
+export {
+  openMsegatChannel,
+  openTaqnyatChannel,
+  openTaqnyatMailChannel,
+  openTaqnyatWhatsAppChannel,
+  openUnifonicChannel,
+};
+
+/** Which MENA providers to open. Omitted providers are skipped. */
+export interface MenaChannelOptions {
+  readonly sms?: ChannelOpenOptions;
+  readonly unifonic?: ChannelOpenOptions;
+  readonly msegat?: ChannelOpenOptions;
+  readonly mail?: ChannelOpenOptions;
+  readonly whatsapp?: ChannelOpenOptions;
+}
+
+/**
+ * Open the MENA drivers that have options.
+ *
+ * @param options - Per-provider credentials (`bearerToken` / `sender` / …)
+ */
+export function menaChannels(options: MenaChannelOptions = {}): ChannelDriver[] {
+  const drivers: ChannelDriver[] = [];
+  if (options.sms) drivers.push(openTaqnyatChannel(options.sms));
+  if (options.unifonic) drivers.push(openUnifonicChannel(options.unifonic));
+  if (options.msegat) drivers.push(openMsegatChannel(options.msegat));
+  if (options.mail) drivers.push(openTaqnyatMailChannel(options.mail));
+  if (options.whatsapp) drivers.push(openTaqnyatWhatsAppChannel(options.whatsapp));
+  return drivers;
+}
+
+/**
+ * Headline plugin. Attach with `.plug(mena())`. Drivers come from
+ * {@link menaChannels}; this registration is the product name.
+ *
+ * @param options - Unused today; reserved for plugin config
+ */
+export function mena(options: MenaChannelOptions = {}): PluginDef {
+  return plugin("mena", { version: "1", config: options });
+}