alepha 0.20.3 → 0.20.4

package/src/datetime/providers/DateTimeProvider.ts

@@ -9,24 +9,189 @@ import { $hook, $inject, Alepha } from "alepha";
 import DayjsApi, {
   type Dayjs,
   type ManipulateType,
+  type OpUnitType,
   type PluginFunc,
+  type QUnitType,
 } from "dayjs";
-import dayjsDuration from "dayjs/plugin/duration.js";
+import dayjsDuration, { type DurationUnitType } from "dayjs/plugin/duration.js";
 import dayjsLocalizedFormat from "dayjs/plugin/localizedFormat.js";
 import dayjsRelativeTime from "dayjs/plugin/relativeTime.js";
 import dayjsTimezone from "dayjs/plugin/timezone.js";
 import dayjsUtc from "dayjs/plugin/utc.js";
 
-export type DateTime = DayjsApi.Dayjs;
-export type Duration = dayjsDuration.Duration;
-export type DurationLike =
-  | number
-  | dayjsDuration.Duration
-  | [number, ManipulateType];
+export type { DurationUnitType, ManipulateType, OpUnitType, QUnitType };
+
+export type DateTimeInput = string | number | Date | DateTime | Dayjs;
+
+export type DurationLike = number | Duration | [number, ManipulateType];
+
+/**
+ * Immutable wrapper around the underlying date-time engine.
+ *
+ * Designed to isolate consumers from the engine in use (currently dayjs).
+ * Methods that produce a new value return a new `DateTime` instance.
+ */
+export class DateTime {
+  protected readonly inner: Dayjs;
+
+  constructor(inner: Dayjs) {
+    this.inner = inner;
+  }
+
+  /**
+   * Add a duration to this date-time.
+   */
+  add(amount: number, unit?: ManipulateType): DateTime;
+  add(duration: Duration): DateTime;
+  add(amount: number | Duration, unit?: ManipulateType): DateTime {
+    if (amount instanceof Duration) {
+      return new DateTime(this.inner.add(amount.toDayjs()));
+    }
+    return new DateTime(this.inner.add(amount, unit));
+  }
+
+  /**
+   * Subtract a duration from this date-time.
+   */
+  subtract(amount: number, unit?: ManipulateType): DateTime;
+  subtract(duration: Duration): DateTime;
+  subtract(amount: number | Duration, unit?: ManipulateType): DateTime {
+    if (amount instanceof Duration) {
+      return new DateTime(this.inner.subtract(amount.toDayjs()));
+    }
+    return new DateTime(this.inner.subtract(amount, unit));
+  }
+
+  startOf(unit: OpUnitType): DateTime {
+    return new DateTime(this.inner.startOf(unit));
+  }
+
+  endOf(unit: OpUnitType): DateTime {
+    return new DateTime(this.inner.endOf(unit));
+  }
+
+  isAfter(other: DateTimeInput): boolean {
+    return this.inner.isAfter(toDayjs(other));
+  }
+
+  isBefore(other: DateTimeInput): boolean {
+    return this.inner.isBefore(toDayjs(other));
+  }
+
+  isSame(other: DateTimeInput, unit?: OpUnitType): boolean {
+    return this.inner.isSame(toDayjs(other), unit);
+  }
+
+  diff(other: DateTimeInput, unit?: QUnitType | OpUnitType): number {
+    return this.inner.diff(toDayjs(other), unit);
+  }
+
+  tz(timezone: string): DateTime {
+    return new DateTime(this.inner.tz(timezone));
+  }
+
+  locale(lang: string): DateTime {
+    return new DateTime(this.inner.locale(lang));
+  }
+
+  format(template?: string): string {
+    return this.inner.format(template);
+  }
+
+  fromNow(withoutSuffix?: boolean): string {
+    return this.inner.fromNow(withoutSuffix);
+  }
+
+  toISOString(): string {
+    return this.inner.toISOString();
+  }
+
+  toDate(): Date {
+    return this.inner.toDate();
+  }
+
+  valueOf(): number {
+    return this.inner.valueOf();
+  }
+
+  unix(): number {
+    return this.inner.unix();
+  }
+
+  toJSON(): string {
+    return this.inner.toISOString();
+  }
+
+  toString(): string {
+    return this.inner.toISOString();
+  }
+
+  /**
+   * Escape hatch for the underlying dayjs instance.
+   *
+   * Use sparingly — anything calling this becomes coupled to dayjs and
+   * will need to migrate when the engine is replaced.
+   */
+  toDayjs(): Dayjs {
+    return this.inner;
+  }
+}
+
+/**
+ * Immutable wrapper around the underlying duration engine.
+ */
+export class Duration {
+  protected readonly inner: dayjsDuration.Duration;
+
+  constructor(inner: dayjsDuration.Duration) {
+    this.inner = inner;
+  }
+
+  asMilliseconds(): number {
+    return this.inner.asMilliseconds();
+  }
+
+  asSeconds(): number {
+    return this.inner.asSeconds();
+  }
+
+  asMinutes(): number {
+    return this.inner.asMinutes();
+  }
+
+  asHours(): number {
+    return this.inner.asHours();
+  }
+
+  asDays(): number {
+    return this.inner.asDays();
+  }
+
+  as(unit: DurationUnitType): number {
+    return this.inner.as(unit);
+  }
+
+  toISOString(): string {
+    return this.inner.toISOString();
+  }
+
+  /**
+   * Escape hatch for the underlying dayjs duration.
+   */
+  toDayjs(): dayjsDuration.Duration {
+    return this.inner;
+  }
+}
 
-export const dayjs = DayjsApi;
 export const isDateTime = (value: unknown): value is DateTime => {
-  return dayjs.isDayjs(value);
+  return value instanceof DateTime;
+};
+
+const toDayjs = (value: DateTimeInput): Dayjs => {
+  if (value instanceof DateTime) {
+    return value.toDayjs();
+  }
+  return DayjsApi(value as any);
 };
 
 export class DateTimeProvider {
@@ -45,7 +210,7 @@ export class DateTimeProvider {
 
   constructor() {
     for (const plugin of DateTimeProvider.PLUGINS) {
-      dayjs.extend(plugin);
+      DayjsApi.extend(plugin);
     }
   }
 
@@ -81,33 +246,34 @@ export class DateTimeProvider {
   });
 
   public setLocale(locale: string): void {
-    dayjs.locale(locale);
+    DayjsApi.locale(locale);
   }
 
   public isDateTime(value: unknown): value is DateTime {
-    return dayjs.isDayjs(value);
+    return value instanceof DateTime;
   }
 
   /**
    * Create a new UTC DateTime instance.
    */
-  public utc(
-    date: string | number | Date | Dayjs | null | undefined,
-  ): DateTime {
-    return dayjs.utc(date);
+  public utc(date: DateTimeInput | null | undefined): DateTime {
+    return new DateTime(DayjsApi.utc(unwrap(date)));
   }
 
   /**
    * Create a new DateTime instance.
    */
-  public of(date: string | number | Date | Dayjs | null | undefined): DateTime {
-    return dayjs(date);
+  public of(date: DateTimeInput | null | undefined): DateTime {
+    if (date instanceof DateTime) {
+      return date;
+    }
+    return new DateTime(DayjsApi(date as any));
   }
 
   /**
    * Get the current date as a string.
    */
-  public toISOString(date: Date | string | DateTime = this.now()): string {
+  public toISOString(date: DateTimeInput = this.now()): string {
     return this.of(date).toISOString();
   }
 
@@ -152,7 +318,7 @@ export class DateTimeProvider {
       return this.ref;
     }
 
-    return dayjs();
+    return new DateTime(DayjsApi());
   }
 
   /**
@@ -162,12 +328,16 @@ export class DateTimeProvider {
     duration: DurationLike,
     unit?: ManipulateType,
   ): Duration => {
+    if (duration instanceof Duration) {
+      return duration;
+    }
+
     if (Array.isArray(duration)) {
-      return dayjs.duration(duration[0], duration[1]);
+      return new Duration(DayjsApi.duration(duration[0], duration[1]));
     }
 
     if (typeof duration === "number") {
-      return dayjs.duration(duration, unit || "milliseconds");
+      return new Duration(DayjsApi.duration(duration, unit || "milliseconds"));
     }
 
     return duration;
@@ -175,7 +345,9 @@ export class DateTimeProvider {
 
   public isDurationLike(value: unknown): value is DurationLike {
     try {
-      return dayjs.isDuration(this.duration(value as DurationLike));
+      return DayjsApi.isDuration(
+        this.duration(value as DurationLike).toDayjs(),
+      );
     } catch {
       return false;
     }
@@ -261,7 +433,7 @@ export class DateTimeProvider {
   ): Timeout {
     if (this.ref && now) {
       const next = this.of(now).add(this.duration(duration));
-      if (next < this.now()) {
+      if (next.valueOf() < this.now().valueOf()) {
         callback();
       }
       return {
@@ -403,6 +575,13 @@ export class DateTimeProvider {
   }
 }
 
+const unwrap = (value: DateTimeInput | null | undefined): any => {
+  if (value instanceof DateTime) {
+    return value.toDayjs();
+  }
+  return value;
+};
+
 export interface Interval {
   timer?: any;
   duration: number;

package/src/lock/core/index.ts

@@ -13,6 +13,37 @@ export * from "./providers/MemoryLockProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Fires when a lock is successfully acquired.
+     */
+    "lock:acquired": {
+      name: string;
+      id: string;
+      maxDurationMs: number;
+    };
+    /**
+     * Fires when a lock is released (handler completed or threw).
+     */
+    "lock:released": {
+      name: string;
+      id: string;
+      heldMs: number;
+    };
+    /**
+     * Fires when a lock acquisition contends with another holder.
+     * Emitted whether the caller eventually acquires (`wait: true`) or fails.
+     */
+    "lock:contended": {
+      name: string;
+      id: string;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * Resource locking for distributed systems.
  *

package/src/lock/core/primitives/$lock.ts

@@ -43,7 +43,7 @@ export const $lock = (options: LockMiddlewareOptions): Middleware => {
   return createMiddleware({
     name: "$lock",
     options: options as unknown as Record<string, unknown>,
-    handler: ({ next }) => {
+    handler: ({ alepha, next }) => {
       const id = crypto.randomUUID();
       const maxDurationMs = dateTimeProvider
         .duration(options.maxDuration ?? [5, "minutes"])
@@ -71,11 +71,13 @@ export const $lock = (options: LockMiddlewareOptions): Middleware => {
 
         // Lock already ended (grace period active)
         if (endedAtStr) {
+          await alepha.events.emit("lock:contended", { name, id });
           throw new LockAcquireError(name);
         }
 
         // Lock held by someone else
         if (lockId !== id) {
+          await alepha.events.emit("lock:contended", { name, id });
           if (options.wait) {
             // Poll until lock is released
             const start = dateTimeProvider.nowMillis();
@@ -109,10 +111,21 @@ export const $lock = (options: LockMiddlewareOptions): Middleware => {
         }
 
         // We hold the lock — execute handler
+        const acquiredAt = dateTimeProvider.nowMillis();
+        await alepha.events.emit("lock:acquired", {
+          name,
+          id,
+          maxDurationMs,
+        });
         try {
           return await next(...args);
         } finally {
           await lockProvider.del(name);
+          await alepha.events.emit("lock:released", {
+            name,
+            id,
+            heldMs: dateTimeProvider.nowMillis() - acquiredAt,
+          });
         }
       };
     },

package/src/mcp/__tests__/jsonrpc.spec.ts

@@ -25,7 +25,7 @@ describe("jsonrpc constants", () => {
   });
 
   test("MCP_PROTOCOL_VERSION should be defined", () => {
-    expect(MCP_PROTOCOL_VERSION).toBe("2024-11-05");
+    expect(MCP_PROTOCOL_VERSION).toBe("2025-11-25");
   });
 
   test("JsonRpcErrorCodes should have correct values", () => {

package/src/mcp/helpers/jsonrpc.ts

@@ -12,7 +12,32 @@ import type {
 
 export const JSONRPC_VERSION = "2.0" as const;
 
-export const MCP_PROTOCOL_VERSION = "2024-11-05" as const;
+/**
+ * The latest MCP protocol revision Alepha targets.
+ * See {@link SUPPORTED_PROTOCOL_VERSIONS} for the full negotiation list.
+ */
+export const MCP_PROTOCOL_VERSION = "2025-11-25" as const;
+
+/**
+ * Protocol versions Alepha will accept during `initialize` negotiation,
+ * highest preference first. The server echoes back whichever version the
+ * client requested if it appears here, otherwise picks the first entry.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+] as const;
+
+export type SupportedProtocolVersion =
+  (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
+
+export const isSupportedProtocolVersion = (
+  v: unknown,
+): v is SupportedProtocolVersion =>
+  typeof v === "string" &&
+  (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(v);
 
 export const JsonRpcErrorCodes = {
   PARSE_ERROR: -32700,

package/src/mcp/index.ts

@@ -3,7 +3,7 @@ import { $prompt } from "./primitives/$prompt.ts";
 import { $resource } from "./primitives/$resource.ts";
 import { $tool } from "./primitives/$tool.ts";
 import { McpServerProvider } from "./providers/McpServerProvider.ts";
-import { SseMcpTransport } from "./transports/SseMcpTransport.ts";
+import { StreamableHttpMcpTransport } from "./transports/StreamableHttpMcpTransport.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -28,12 +28,15 @@ export {
   createParseError,
   createResponse,
   isNotification,
+  isSupportedProtocolVersion,
   isValidJsonRpcRequest,
   JSONRPC_VERSION,
   JsonRpcErrorCodes,
   JsonRpcParseError,
   MCP_PROTOCOL_VERSION,
   parseMessage,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  type SupportedProtocolVersion,
 } from "./helpers/jsonrpc.ts";
 export type {
   JsonRpcError,
@@ -88,8 +91,10 @@ export { $tool, ToolPrimitive } from "./primitives/$tool.ts";
 export { McpServerProvider } from "./providers/McpServerProvider.ts";
 export {
   mcpSseOptions,
+  mcpStreamableHttpOptions,
   SseMcpTransport,
-} from "./transports/SseMcpTransport.ts";
+  StreamableHttpMcpTransport,
+} from "./transports/StreamableHttpMcpTransport.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -101,7 +106,7 @@ export {
  * - MCP tool definitions
  * - MCP prompt definitions
  * - JSON-RPC protocol
- * - SSE and Stdio transports
+ * - Streamable HTTP transport (spec 2025-03-26+)
  *
  * @module alepha.mcp
  */
@@ -109,6 +114,6 @@ export const AlephaMcp = $module({
   name: "alepha.mcp",
   primitives: [$tool, $resource, $prompt],
   services: [McpServerProvider],
-  // Transports are opt-in — user wires the one(s) they need via alepha.with(SseMcpTransport).
-  variants: [SseMcpTransport],
+  // Transports are opt-in — user wires the one(s) they need via alepha.with(StreamableHttpMcpTransport).
+  variants: [StreamableHttpMcpTransport],
 });

package/src/mcp/interfaces/McpTypes.ts

@@ -40,14 +40,48 @@ export interface McpCapabilities {
   prompts?: Record<string, never>;
 }
 
+/**
+ * Spec 2025-11-25: optional `description` aligns with the MCP registry's
+ * `server.json` format and provides human-readable context during init.
+ */
 export interface McpServerInfo {
   name: string;
   version: string;
+  description?: string;
 }
 
 export interface McpClientInfo {
   name: string;
   version: string;
+  description?: string;
+}
+
+/**
+ * Icon descriptor (spec 2025-11-25 / SEP-973). Mirrors web app manifest
+ * icon shape — clients render these in tool palettes / picker UIs.
+ */
+export interface McpIcon {
+  src: string;
+  mimeType?: string;
+  sizes?: string;
+}
+
+/**
+ * Tool annotations (spec 2025-03-26+). Hints to the client about how to
+ * present and gate the tool. None are guarantees — the client uses these
+ * heuristically (e.g. to show a confirmation prompt for destructive tools).
+ */
+export interface McpToolAnnotations {
+  /** Human-friendly display title (distinct from `name`, the programmatic id). */
+  title?: string;
+  /** Tool reads only; safe to auto-approve. */
+  readOnlyHint?: boolean;
+  /** Tool may delete or overwrite data; client should require confirmation. */
+  destructiveHint?: boolean;
+  /** Calling the tool with the same args twice yields the same end state. */
+  idempotentHint?: boolean;
+  /** Tool interacts with the open world (network, etc.) vs. a closed system. */
+  openWorldHint?: boolean;
 }
 
 export interface McpInitializeParams {
@@ -68,14 +102,27 @@ export interface McpInitializeResult {
 
 export interface McpToolDescriptor {
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description: string;
   inputSchema: McpJsonSchema;
+  /** Output schema enabling `structuredContent` on call results (spec 2025-06-18). */
+  outputSchema?: McpJsonSchema;
+  /** Behavior hints (spec 2025-03-26+). */
+  annotations?: McpToolAnnotations;
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpJsonSchema {
   type: string;
   properties?: Record<string, unknown>;
   required?: string[];
+  /** JSON Schema dialect (spec 2025-11-25 / SEP-1613 — defaults to 2020-12). */
+  $schema?: string;
+  [key: string]: unknown;
 }
 
 export interface McpToolCallParams {
@@ -85,15 +132,33 @@ export interface McpToolCallParams {
 
 export interface McpToolCallResult {
   content: McpContent[];
+  /**
+   * Structured tool output (spec 2025-06-18). When the tool declares an
+   * `outputSchema`, the server MUST populate `structuredContent`; the
+   * `content` array carrying a JSON-stringified text block is kept as
+   * a back-compat fallback for older clients.
+   */
+  structuredContent?: unknown;
   isError?: boolean;
+  _meta?: Record<string, unknown>;
 }
 
-export interface McpContent {
-  type: "text" | "image" | "resource";
-  text?: string;
-  data?: string;
-  mimeType?: string;
-}
+/**
+ * Discriminated content union covering text, image, audio (added 2025-03-26),
+ * inlined resources, and resource links (added 2025-06-18).
+ */
+export type McpContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: McpResourceContent }
+  | {
+      type: "resource_link";
+      uri: string;
+      name: string;
+      description?: string;
+      mimeType?: string;
+    };
 
 // ---------------------------------------------------------------------------------------------------------------------
 // Resource Types
@@ -102,8 +167,14 @@ export interface McpContent {
 export interface McpResourceDescriptor {
   uri: string;
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description?: string;
   mimeType?: string;
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpResourceReadParams {
@@ -127,8 +198,14 @@ export interface McpResourceContent {
 
 export interface McpPromptDescriptor {
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description?: string;
   arguments?: McpPromptArgument[];
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpPromptArgument {

package/src/mcp/primitives/$prompt.ts

@@ -10,6 +10,7 @@ import {
 } from "alepha";
 import type {
   McpContext,
+  McpIcon,
   McpPromptArgument,
   McpPromptDescriptor,
   PromptHandlerArgs,
@@ -80,6 +81,12 @@ export interface PromptPrimitiveOptions<T extends TObject> {
    */
   name?: string;
 
+  /**
+   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
+   * which remains the programmatic identifier.
+   */
+  title?: string;
+
   /**
    * Description of what this prompt does.
    *
@@ -89,6 +96,11 @@ export interface PromptPrimitiveOptions<T extends TObject> {
    */
   description?: string;
 
+  /**
+   * Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
+   */
+  icons?: McpIcon[];
+
   /**
    * TypeBox schema defining the prompt arguments.
    *
@@ -157,13 +169,18 @@ export class PromptPrimitive<T extends TObject> extends Primitive<
    * Convert the prompt to an MCP prompt descriptor for protocol messages.
    */
   public toDescriptor(): McpPromptDescriptor {
-    return {
+    const descriptor: McpPromptDescriptor = {
       name: this.name,
       description: this.description,
       arguments: this.options.args
         ? this.schemaToArguments(this.options.args)
         : [],
     };
+    if (this.options.title) descriptor.title = this.options.title;
+    if (this.options.icons && this.options.icons.length > 0) {
+      descriptor.icons = this.options.icons;
+    }
+    return descriptor;
   }
 
   /**