alepha 0.22.0 → 0.23.0

package/src/cli/platform-lib/adapters/CloudflareAdapter.ts

@@ -1016,8 +1016,10 @@ export class CloudflareAdapter extends PlatformAdapter {
       });
     }
 
-    // 5. Delete R2 bucket (must be emptied first — Cloudflare's REST DELETE
-    // rejects non-empty buckets with `BucketNotEmpty`)
+    // 5. Delete R2 bucket. An empty bucket is removed by the REST DELETE
+    // directly; only a non-empty one needs an S3 wipe first. Crucially the
+    // wipe is NOT a precondition of the delete — a wipe that can't run (no
+    // creds) must never strand an otherwise-deletable bucket.
     const needsBucket = ctx.resources.hasBucket;
     if (needsBucket) {
       const name = ctx.naming.r2();
@@ -1025,14 +1027,10 @@ export class CloudflareAdapter extends PlatformAdapter {
         name: `delete r2 ${name}`,
         handler: async () => {
           try {
-            await this.wipeR2Bucket(name, ctx);
-            await this.api.deleteR2(name);
+            await this.deleteR2Bucket(name, ctx);
           } catch (error: any) {
             const msg = String(error.message || "");
-            if (
-              msg.includes("does not exist") ||
-              msg.includes("NoSuchBucket")
-            ) {
+            if (this.isMissingBucketError(msg)) {
               this.log.debug(`Bucket ${name} not found — skipping.`);
             } else {
               this.log.warn(`Failed to delete r2 ${name}: ${msg}`);
@@ -1128,15 +1126,86 @@ export class CloudflareAdapter extends PlatformAdapter {
     await this.api.createR2(name);
   }
 
+  /** Whether a Cloudflare error message indicates the bucket is already gone. */
+  protected isMissingBucketError(msg: string): boolean {
+    return (
+      msg.includes("does not exist") ||
+      msg.includes("NoSuchBucket") ||
+      msg.includes("bucket not found")
+    );
+  }
+
+  /**
+   * Resolve S3 credentials for wiping an R2 bucket over the S3 protocol.
+   *
+   * Prefers the account's R2 S3 credentials from the environment
+   * (`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`) — these are already
+   * provisioned for the deploy (artifact registry) and are account-scoped,
+   * so they can empty any bucket without minting anything. Returns `null`
+   * when not configured, letting the caller fall back to token minting.
+   */
+  protected resolveR2Credentials(): {
+    accessKeyId: string;
+    secretAccessKey: string;
+  } | null {
+    const accessKeyId = process.env.S3_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.S3_SECRET_ACCESS_KEY;
+    if (accessKeyId && secretAccessKey) {
+      return { accessKeyId, secretAccessKey };
+    }
+    return null;
+  }
+
+  /**
+   * Delete an R2 bucket, emptying it first only when necessary.
+   *
+   * Cloudflare's REST `DELETE /r2/buckets/:name` succeeds on an empty bucket
+   * but rejects a non-empty one. So we attempt the delete directly (the
+   * common teardown case — no objects, no creds needed), and only on failure
+   * empty the bucket over the S3 protocol and retry. A missing bucket is a
+   * no-op, so teardown is idempotent.
+   */
+  protected async deleteR2Bucket(
+    name: string,
+    ctx: PlatformContext,
+  ): Promise<void> {
+    try {
+      await this.api.deleteR2(name);
+      return;
+    } catch (error: any) {
+      const msg = String(error.message || "");
+      if (this.isMissingBucketError(msg)) {
+        return; // already gone
+      }
+      // Most often the bucket is non-empty — empty it then retry once.
+      this.log.debug(
+        `Direct delete of r2 ${name} failed (${msg}); emptying then retrying.`,
+      );
+    }
+
+    await this.wipeR2Bucket(name, ctx);
+
+    try {
+      await this.api.deleteR2(name);
+    } catch (error: any) {
+      const msg = String(error.message || "");
+      if (this.isMissingBucketError(msg)) {
+        return;
+      }
+      throw error;
+    }
+  }
+
   /**
    * Empty an R2 bucket via the S3-compatible API.
    *
-   * Cloudflare's REST `DELETE /r2/buckets/:name` rejects non-empty buckets
-   * with `BucketNotEmpty`, and the REST API has no object-level endpoints —
-   * objects must be listed and deleted over the S3 protocol. To avoid
-   * making users pre-create R2 access keys, we mint a short-lived
-   * bucket-scoped API token using the wrangler bearer token, wipe the
-   * bucket with `s3mini`, then revoke the token.
+   * Cloudflare's REST API has no object-level endpoints — objects must be
+   * listed and deleted over the S3 protocol. We use the account's R2 S3
+   * credentials (`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`) when present;
+   * otherwise we fall back to minting a short-lived bucket-scoped token via
+   * the CF API (requires a user-scoped `CLOUDFLARE_API_TOKEN`) and revoke it
+   * after. When neither is available the wipe is skipped with a warning —
+   * the caller still attempts the delete, which succeeds for empty buckets.
    *
    * Also aborts any pending multipart uploads — those count as bucket
    * contents from R2's perspective and would otherwise block the delete.
@@ -1145,20 +1214,40 @@ export class CloudflareAdapter extends PlatformAdapter {
     bucketName: string,
     ctx: PlatformContext,
   ): Promise<void> {
-    // `createR2Token` calls `POST /accounts/:id/tokens`, which requires
-    // `User → API Tokens → Edit` — only granted on user-level tokens.
-    // A standard account-scoped `CLOUDFLARE_API_TOKEN` 401s on that path,
-    // and the wrangler OAuth bearer doesn't carry the scope either. Without
-    // either, we can't mint the bucket-scoped S3 creds the wipe needs, so
-    // skip and leave the bucket for manual deletion in the dashboard.
-    if (!process.env.CLOUDFLARE_API_TOKEN) {
-      this.log.warn(
-        `Skipping R2 wipe for ${bucketName}: CLOUDFLARE_API_TOKEN not set. Delete the bucket manually in the Cloudflare dashboard.`,
-      );
-      return;
+    let creds = this.resolveR2Credentials();
+    let mintedTokenId: string | undefined;
+
+    if (!creds) {
+      // No env S3 creds — try minting a bucket-scoped token. This needs a
+      // user-scoped `CLOUDFLARE_API_TOKEN`; an account-scoped one (or the
+      // wrangler OAuth bearer) can't mint, so we skip rather than throw and
+      // let the caller's delete attempt proceed (fine for empty buckets).
+      if (!process.env.CLOUDFLARE_API_TOKEN) {
+        this.log.warn(
+          `Skipping R2 wipe for ${bucketName}: no S3 credentials ` +
+            `(S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY) and no ` +
+            `CLOUDFLARE_API_TOKEN to mint a bucket-scoped token. A non-empty ` +
+            `bucket must be emptied manually in the Cloudflare dashboard.`,
+        );
+        return;
+      }
+      try {
+        const tokenName = `alepha-teardown-${bucketName}-${Date.now()}`;
+        const token = await this.api.createR2Token(tokenName, bucketName);
+        mintedTokenId = token.id;
+        creds = {
+          accessKeyId: token.accessKeyId,
+          secretAccessKey: token.secretAccessKey,
+        };
+      } catch (error: any) {
+        this.log.warn(
+          `Skipping R2 wipe for ${bucketName}: could not mint an R2 token ` +
+            `(${String(error.message || "")}). Set S3_ACCESS_KEY_ID / ` +
+            `S3_SECRET_ACCESS_KEY for reliable teardown.`,
+        );
+        return;
+      }
     }
-    const tokenName = `alepha-teardown-${bucketName}-${Date.now()}`;
-    const token = await this.api.createR2Token(tokenName, bucketName);
 
     try {
       const accountId = await this.api.resolveAccountId();
@@ -1168,8 +1257,8 @@ export class CloudflareAdapter extends PlatformAdapter {
         : `${accountId}.r2.cloudflarestorage.com`;
 
       const client = new S3mini({
-        accessKeyId: token.accessKeyId,
-        secretAccessKey: token.secretAccessKey,
+        accessKeyId: creds.accessKeyId,
+        secretAccessKey: creds.secretAccessKey,
         region: "auto",
         endpoint: `https://${host}/${bucketName}`,
       });
@@ -1226,13 +1315,16 @@ export class CloudflareAdapter extends PlatformAdapter {
         this.log.info(`Emptied ${total} object(s) from bucket ${bucketName}.`);
       }
     } finally {
-      // Always revoke, even if the wipe itself failed mid-way.
-      try {
-        await this.api.deleteR2Token(token.id);
-      } catch (error: any) {
-        this.log.warn(
-          `Failed to revoke ephemeral R2 token ${token.id}: ${String(error.message || "")}`,
-        );
+      // Revoke only a token we minted here — env S3 creds are long-lived and
+      // must not be deleted. Always revoke, even if the wipe failed mid-way.
+      if (mintedTokenId) {
+        try {
+          await this.api.deleteR2Token(mintedTokenId);
+        } catch (error: any) {
+          this.log.warn(
+            `Failed to revoke ephemeral R2 token ${mintedTokenId}: ${String(error.message || "")}`,
+          );
+        }
       }
     }
   }

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

@@ -230,6 +230,77 @@ describe("McpServerProvider", () => {
       expect(result.content[0].text).toBe("42");
     });
 
+    test("passes raw MCP content (e.g. image) through verbatim when the tool has no output schema", async () => {
+      const alepha = Alepha.create();
+
+      class ImageTools {
+        screenshot = $tool({
+          description: "Return a tiny image",
+          // No `result` schema — handler returns raw MCP content blocks.
+          handler: async () => ({
+            content: [
+              {
+                type: "image",
+                data: "aGVsbG8=",
+                mimeType: "image/png",
+              },
+            ],
+          }),
+        });
+      }
+
+      alepha.with(AlephaMcp).with(ImageTools);
+      await alepha.start();
+
+      const provider = alepha.inject(McpServerProvider);
+      const response = await provider.handleMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "screenshot", arguments: {} },
+      });
+
+      const result = response?.result as {
+        content: Array<{ type: string; data?: string; mimeType?: string }>;
+        structuredContent?: unknown;
+      };
+      expect(result.content).toHaveLength(1);
+      expect(result.content[0].type).toBe("image");
+      expect(result.content[0].data).toBe("aGVsbG8=");
+      expect(result.content[0].mimeType).toBe("image/png");
+      // Raw content is NOT double-wrapped into a JSON text block.
+      expect(result.structuredContent).toBeUndefined();
+    });
+
+    test("a plain object result (no content array) still serializes to a JSON text block", async () => {
+      const alepha = Alepha.create();
+
+      class PlainTools {
+        info = $tool({
+          description: "Return a plain object",
+          // No `result` schema, but the object is not raw MCP content.
+          handler: async () => ({ hello: "world" }),
+        });
+      }
+
+      alepha.with(AlephaMcp).with(PlainTools);
+      await alepha.start();
+
+      const provider = alepha.inject(McpServerProvider);
+      const response = await provider.handleMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "info", arguments: {} },
+      });
+
+      const result = response?.result as {
+        content: Array<{ type: string; text: string }>;
+      };
+      expect(result.content[0].type).toBe("text");
+      expect(JSON.parse(result.content[0].text)).toEqual({ hello: "world" });
+    });
+
     test("should return error for unknown tool", async () => {
       const alepha = Alepha.create();
       alepha.with(AlephaMcp);

package/src/mcp/providers/McpServerProvider.ts

@@ -19,6 +19,7 @@ import type {
   JsonRpcRequest,
   JsonRpcResponse,
   McpCapabilities,
+  McpContent,
   McpContext,
   McpInitializeResult,
   McpPromptDescriptor,
@@ -309,6 +310,20 @@ export class McpServerProvider {
     try {
       const result = await tool.execute(args, context);
 
+      // A tool WITHOUT an output schema may return raw MCP content blocks
+      // (e.g. an `image` block) instead of JSON — used for binary payloads
+      // like attachment previews. Recognized by the CallToolResult shape
+      // (`{ content: McpContent[] }`); passed through verbatim. Tools that
+      // declare an output schema always go through the structured path
+      // below, so a JSON result that happens to carry a `content` array is
+      // never mistaken for raw content.
+      if (!tool.hasOutputSchema()) {
+        const raw = this.asRawToolContent(result);
+        if (raw) {
+          return raw;
+        }
+      }
+
       const callResult: McpToolCallResult = {
         content: [
           {
@@ -364,6 +379,46 @@ export class McpServerProvider {
     }
   }
 
+  /**
+   * Recognize a tool handler's return value as a pre-built MCP tool result —
+   * i.e. it already carries a `content` array of content blocks (text, image,
+   * audio, resource, resource_link). Returns the normalized
+   * {@link McpToolCallResult} when matched, or `undefined` to fall back to the
+   * default JSON/text encoding. Only ever consulted for tools that did NOT
+   * declare an output schema (see {@link handleToolCall}).
+   */
+  protected asRawToolContent(result: unknown): McpToolCallResult | undefined {
+    if (!result || typeof result !== "object") {
+      return undefined;
+    }
+    const candidate = result as {
+      content?: unknown;
+      isError?: unknown;
+      _meta?: unknown;
+    };
+    if (!Array.isArray(candidate.content) || candidate.content.length === 0) {
+      return undefined;
+    }
+    const allBlocks = candidate.content.every(
+      (block): block is McpContent =>
+        !!block &&
+        typeof block === "object" &&
+        typeof (block as { type?: unknown }).type === "string",
+    );
+    if (!allBlocks) {
+      return undefined;
+    }
+    return {
+      content: candidate.content as McpContent[],
+      isError:
+        typeof candidate.isError === "boolean" ? candidate.isError : undefined,
+      _meta:
+        candidate._meta && typeof candidate._meta === "object"
+          ? (candidate._meta as Record<string, unknown>)
+          : undefined,
+    };
+  }
+
   protected handleResourcesList(): { resources: McpResourceDescriptor[] } {
     return {
       resources: Array.from(this.resources.values()).map((r) =>

package/src/react/form/__tests__/FormModel-submit-loading.spec.ts

@@ -0,0 +1,71 @@
+import { Alepha, t } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { describe, it } from "vitest";
+import { FormModel } from "../services/FormModel.ts";
+
+/**
+ * Repro for: a form whose submit fails TypeBox validation (missing field)
+ * leaves the submit button stuck in its loading state forever.
+ *
+ * The button's loading is driven by the `form:submit:begin` / `form:submit:end`
+ * event pair (see useFormState). So the invariant that matters is: every
+ * `form:submit:begin` is followed by a `form:submit:end`, even when validation
+ * throws AND even when a downstream error listener (e.g. the action-error
+ * toaster) itself throws.
+ */
+describe("FormModel.submit loading pairing", () => {
+  const makeForm = (alepha: Alepha) =>
+    alepha.inject(FormModel as any, {
+      lifetime: "transient",
+      args: [
+        "f1",
+        {
+          id: "f1",
+          schema: t.object({ email: t.text(), password: t.text() }),
+          handler: () => {},
+          initialValues: {}, // both required fields missing → decode throws
+        },
+      ],
+    }) as FormModel<any>;
+
+  it("emits form:submit:end on a validation error (intrinsic)", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let begun = false;
+    let ended = false;
+    alepha.events.on("form:submit:begin", () => {
+      begun = true;
+    });
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(begun).toBe(true);
+    expect(ended).toBe(true); // pairing must hold
+  });
+
+  it("emits form:submit:end even when a react:action:error listener throws", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let ended = false;
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+    // Simulates a globally-mounted listener (e.g. ActionErrorToaster) throwing.
+    alepha.events.on("react:action:error", () => {
+      throw new Error("toaster boom");
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(ended).toBe(true); // currently FAILS: end is skipped → button stuck
+  });
+});

package/src/react/form/__tests__/form-submitting-reactive.browser.spec.tsx

@@ -0,0 +1,96 @@
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { Alepha, t } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { AlephaContext } from "alepha/react";
+import { describe, it } from "vitest";
+import { useForm, useFormState } from "../index.ts";
+
+/**
+ * Submit buttons bind their loading state to `useFormState(form, ["loading"])`
+ * (the reactive form-state API; the non-reactive `form.submitting` getter was
+ * removed). This loading must:
+ *  - turn ON while an async submit is in flight, and
+ *  - turn OFF again afterwards — including after a TypeBox validation error.
+ *
+ * The OFF guarantee relies on `FormModel.submit` always emitting
+ * `form:submit:end` (see FormModel-submit-loading.spec.ts).
+ */
+describe("useFormState loading drives the submit button", () => {
+  const mount = (alepha: Alepha, ui: React.ReactNode) =>
+    render(
+      <AlephaContext.Provider value={alepha}>{ui}</AlephaContext.Provider>,
+    );
+
+  it("turns loading on during an async submit and off after", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    let release!: () => void;
+
+    const Form = () => {
+      const form = useForm({
+        id: "async",
+        schema: t.object({ name: t.string({ minLength: 1 }) }),
+        initialValues: { name: "ok" },
+        handler: () => new Promise<void>((r) => (release = r)),
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            go
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form"));
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("true"),
+    );
+    release();
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+
+  it("clears loading after a TypeBox validation error", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+
+    const Form = () => {
+      const form = useForm({
+        id: "login",
+        schema: t.object({
+          identifier: t.string({ minLength: 1 }),
+          password: t.string({ minLength: 6 }),
+        }),
+        handler: async () => {},
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            Sign in
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form")); // empty → validation error
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+});

package/src/react/form/services/FormModel.ts

@@ -27,10 +27,6 @@ export class FormModel<T extends TObject> {
 
   public input: SchemaToInput<T>;
 
-  public get submitting(): boolean {
-    return this.submitInProgress;
-  }
-
   constructor(
     public readonly id: string,
     public readonly options: FormCtrlOptions<T>,
@@ -185,14 +181,22 @@ export class FormModel<T extends TObject> {
       return;
     }
 
-    // emit both action and form events
-    await this.alepha.events.emit("react:action:begin", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:begin", {
-      id: this.id,
-    });
+    // Lifecycle events are best-effort NOTIFICATIONS (loading spinners, toasts,
+    // analytics). A misbehaving listener must never break form state or reject
+    // submit() — hence `{ catch: true }` on every emit below. Without it, a
+    // throwing `react:action:error`/`form:submit:error` listener would skip the
+    // `form:submit:end` "loading off" signal and leave submit buttons stuck in
+    // their loading state forever.
+    await this.alepha.events.emit(
+      "react:action:begin",
+      { type: "form", id: this.id },
+      { catch: true },
+    );
+    await this.alepha.events.emit(
+      "form:submit:begin",
+      { id: this.id },
+      { catch: true },
+    );
 
     this.submitInProgress = true;
 
@@ -210,39 +214,53 @@ export class FormModel<T extends TObject> {
 
       await options.handler(values as any);
 
-      await this.alepha.events.emit("react:action:success", {
-        type: "form",
-        id: this.id,
-      });
-      await this.alepha.events.emit("form:submit:success", {
-        id: this.id,
-        values,
-      });
+      await this.alepha.events.emit(
+        "react:action:success",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:success",
+        { id: this.id, values },
+        { catch: true },
+      );
     } catch (error) {
       this.log.error("Form submission error:", error);
 
-      options.onError?.(error as Error);
-
-      await this.alepha.events.emit("react:action:error", {
-        type: "form",
-        id: this.id,
-        error: error as Error,
-      });
-      await this.alepha.events.emit("form:submit:error", {
-        error: error as Error,
-        id: this.id,
-      });
+      // A throwing onError callback must not abort the lifecycle either.
+      try {
+        options.onError?.(error as Error);
+      } catch (handlerError) {
+        this.log.error("Form onError handler threw:", handlerError);
+      }
+
+      await this.alepha.events.emit(
+        "react:action:error",
+        { type: "form", id: this.id, error: error as Error },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:error",
+        { error: error as Error, id: this.id },
+        { catch: true },
+      );
     } finally {
       this.submitInProgress = false;
-    }
 
-    await this.alepha.events.emit("react:action:end", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:end", {
-      id: this.id,
-    });
+      // The "loading off" signals live in `finally` so they ALWAYS fire,
+      // even if something above threw — guaranteeing the begin/end pairing
+      // that drives submit-button loading state.
+      await this.alepha.events.emit(
+        "react:action:end",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:end",
+        { id: this.id },
+        { catch: true },
+      );
+    }
   };
 
   /**