Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.2 KB
Raw Blame
/**
 * Which messaging failures the dashboard counts as needing a human.
 *
 * The rule under test is the recorder's own criterion — "does a human need to step in" — and
 * it answers from the error's type AND the capture point's code, because the same refusal is
 * routine where the chat was handed the fix and waits for a human where nobody was. The cost
 * center highlights the unexpected count, so getting either half wrong points that highlight
 * at nothing, or hides the one failure worth an alert.
 *
 * Only the two halves live here; that the classification reaches `error_records` this way is
 * proved end to end in messaging.test.ts and messaging-qq.test.ts, and the verdicts a failure
 * carries are asserted where the transports decide them (messaging-wire.test.ts and the qq and
 * wechat transport suites).
 */
import { describe, expect, it } from "vitest";
import { MessagingChannelError } from "../src/runtime/messaging/connector.js";
import { messagingErrorKind } from "../src/runtime/messaging/error-kind.js";
import {
  MessagingMediaTooLargeError,
  MessagingOutboundCapError,
  MessagingPermissionError,
  MessagingUnsupportedError,
} from "../src/runtime/messaging/media.js";
import { MessagingConnectionClosedError } from "../src/runtime/messaging/qq-api.js";
import { TelegramApiError } from "../src/runtime/messaging/telegram-api.js";

/** Feishu's 99991672, which every one of its calls throws alike — the point of the code half. */
const scopeDenial = (): MessagingPermissionError =>
  new MessagingPermissionError(
    ["im:message", "im:message.history:readonly"],
    "https://open.feishu.cn/app/cli_x/auth?q=im:message",
    "Access denied. One of the following scopes is required (code 99991672)",
  );

/** QQ's refusal of any outbound file, which the platform repeats identically every time. */
const qqFileRefusal = (): MessagingUnsupportedError =>
  new MessagingUnsupportedError('QQ cannot receive "chart.png": requires a public URL');

describe("messagingErrorKind", () => {
  it("files a typed refusal as expected on an inbound download, where the chat was told", () => {
    // The inbound download answers into the chat with the scope names and the console link:
    // it has already handed the fix to the only person who can apply it, so a dashboard adds
    // nothing.
    expect(messagingErrorKind(scopeDenial(), "messaging_image_fetch_failed")).toBe("expected");
    // An inbound FILE download is the same capture point in every way that matters here: on
    // Feishu it is the very same scope denial, answered into the chat with the same scope
    // names and console link (see messagingInboundFilePermissionNotice).
    expect(messagingErrorKind(scopeDenial(), "messaging_file_fetch_failed")).toBe("expected");
    // The same denial on a send, which is the ordinary half-configured app: nothing reaches
    // the chat, because the message that would carry the notice is the one being refused.
    expect(messagingErrorKind(scopeDenial(), "messaging_send_failed")).toBe("unexpected");
    expect(messagingErrorKind(scopeDenial(), "messaging_inbound_failed")).toBe("unexpected");
  });

  it("files an outbound file refusal as expected only when nobody has anything to fix", () => {
    // A reply's file that did not go out is recorded and never posted into the chat, so
    // nobody is told anything there. What stays routine is what nobody could act on: a
    // channel that can never carry a file...
    expect(messagingErrorKind(qqFileRefusal(), "messaging_file_send_failed")).toBe("expected");
    // ...and the bridge's own caps, per file and per reply.
    expect(
      messagingErrorKind(
        new MessagingOutboundCapError('"huge.png" was not sent: over the 10MB limit'),
        "messaging_file_too_large",
      ),
    ).toBe("expected");
    expect(
      messagingErrorKind(
        new MessagingOutboundCapError("2 more files were not sent: at most 5 per reply"),
        "messaging_files_skipped",
      ),
    ).toBe("expected");
    // A missing permission on the upload is NOT: the same denial is routine on an inbound
    // download because the chat is handed the fix there, while here nobody is handed
    // anything, and a human still has to grant the scope.
    expect(messagingErrorKind(scopeDenial(), "messaging_file_send_failed")).toBe("unexpected");
    // Nor anything else the upload throws.
    expect(messagingErrorKind(new Error("upload rejected"), "messaging_file_send_failed")).toBe(
      "unexpected",
    );
    expect(
      messagingErrorKind(
        new MessagingMediaTooLargeError("The file", 30 * 1024 * 1024),
        "messaging_file_send_failed",
      ),
    ).toBe("unexpected");
  });

  it("holds each outbound type to its own capture point", () => {
    // The allowlist pairs a type with a code. The cap error is routine where the bridge files
    // it and nowhere else, and the structural refusal is not routine at the caps' codes.
    expect(
      messagingErrorKind(new MessagingOutboundCapError("over a cap"), "messaging_send_failed"),
    ).toBe("unexpected");
    expect(
      messagingErrorKind(new MessagingOutboundCapError("over a cap"), "messaging_file_send_failed"),
    ).toBe("unexpected");
    expect(messagingErrorKind(qqFileRefusal(), "messaging_file_too_large")).toBe("unexpected");
    // And a plain Error at the caps' own codes is still unclassified: the type is half the rule.
    expect(messagingErrorKind(new Error("over a cap"), "messaging_file_too_large")).toBe(
      "unexpected",
    );
    expect(messagingErrorKind(new Error("over a cap"), "messaging_files_skipped")).toBe(
      "unexpected",
    );
  });

  it("leaves everything it has not been taught about unexpected, wording included", () => {
    // The safe direction: a real fault miscounted as routine is invisible, while routine noise
    // miscounted as a fault is merely loud. A plain Error repeating a permission error's words
    // is still unclassified — matching on wording would make the count depend on how a
    // platform phrases its refusal.
    expect(messagingErrorKind(new Error("socket hang up"), "messaging_image_fetch_failed")).toBe(
      "unexpected",
    );
    expect(
      messagingErrorKind(
        new Error("Access denied (code 99991672)"),
        "messaging_image_fetch_failed",
      ),
    ).toBe("unexpected");
    expect(messagingErrorKind(undefined, "messaging_connect_failed")).toBe("unexpected");
  });

  it("a platform close is read from its own verdict, not from the capture point", () => {
    // Classified by its own verdict wherever it is caught, including capture points the sets
    // above deliberately exclude: nobody needs telling because the connector's next handshake
    // already put the connection back.
    expect(
      messagingErrorKind(
        new MessagingConnectionClosedError("gateway connection closed (code 4009)", 4009, true),
        "messaging_connect_failed",
      ),
    ).toBe("expected");
    // A close that leaves the binding down until a person changes a credential or a console
    // setting keeps its place on the dashboard, whatever number it carries.
    expect(
      messagingErrorKind(
        new MessagingConnectionClosedError("gateway connection closed (code 4004)", 4004, false),
        "messaging_connect_failed",
      ),
    ).toBe("unexpected");
    expect(
      messagingErrorKind(
        new MessagingConnectionClosedError("gateway refused this bot", 4914, false),
        "messaging_connect_failed",
      ),
    ).toBe("unexpected");
    // The verdict travels with the type, so it holds wherever the failure is caught.
    expect(
      messagingErrorKind(
        new MessagingConnectionClosedError("gateway connection closed (code 4009)", 4009, true),
        "messaging_inbound_failed",
      ),
    ).toBe("expected");
    // And a plain Error that merely quotes the code is not one: matching on wording would tie
    // the count to how a platform phrases its own close.
    expect(
      messagingErrorKind(
        new Error("gateway connection closed (code 4009)"),
        "messaging_connect_failed",
      ),
    ).toBe("unexpected");
  });

  it("a connection failure or a text send is read from the connector's own verdict", () => {
    // The two capture points where the chat hears nothing and the only question is whether
    // anybody has to act. A failure the next attempt gets past is routine there…
    const blip = new MessagingChannelError("getUpdates failed: socket hang up", true);
    expect(messagingErrorKind(blip, "messaging_connect_failed")).toBe("expected");
    expect(messagingErrorKind(blip, "messaging_send_failed")).toBe("expected");
    expect(
      messagingErrorKind(
        new TelegramApiError(
          "sendMessage failed: Too Many Requests: retry after 5 (code 429)",
          429,
        ),
        "messaging_send_failed",
      ),
    ).toBe("expected");
    // …and one that meets the same refusal every time stays a defect, whichever channel's
    // type carries the verdict.
    expect(
      messagingErrorKind(
        new MessagingChannelError("Token exchange failed: appid invalid (code 100007)", false),
        "messaging_connect_failed",
      ),
    ).toBe("unexpected");
    expect(
      messagingErrorKind(
        new TelegramApiError(
          "sendMessage failed: Forbidden: bot was blocked by the user (code 403)",
          403,
        ),
        "messaging_send_failed",
      ),
    ).toBe("unexpected");
    // A plain Error carries no verdict, whatever its words say: unclassified stays loud.
    expect(
      messagingErrorKind(
        new Error("getUpdates failed: socket hang up"),
        "messaging_connect_failed",
      ),
    ).toBe("unexpected");
  });

  it("reads that verdict at those two capture points and nowhere else", () => {
    // The same transports throw at the file and download capture points, which answer the
    // question by type and code: a reply's file that did not go out is said nowhere but its
    // record, and whether the upload would work next time does not change that.
    const blip = new MessagingChannelError("sendPhoto failed: socket hang up", true);
    expect(messagingErrorKind(blip, "messaging_file_send_failed")).toBe("unexpected");
    expect(messagingErrorKind(blip, "messaging_image_fetch_failed")).toBe("unexpected");
    expect(messagingErrorKind(blip, "messaging_inbound_failed")).toBe("unexpected");
  });
});