@ithousecall/chat 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Limn LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @ithousecall/chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+@housecall is a self-hosted IT helpdesk agent for Slack, Microsoft Teams and Google Chat. It answers from your IT docs
+(a local folder, Google Drive, Confluence), acts through MCP servers and TypeScript tools, and asks the requester to
+confirm any tool that changes something. It runs as one Node 24 process with its state in SQLite.
+
+**To self-host @housecall, start from [it-housecall-chat-agent](https://github.com/IT-Housecall/it-housecall-chat-agent)**:
+create your repository from that template and follow its README. This package is the engine the template installs; you
+don't need to install it yourself. Docs: https://chat.ithousecall.app/docs/quickstart
+
+To upgrade a project, run `npm install @ithousecall/chat@latest`, commit `package.json` and `package-lock.json`, and rebuild the
+image.
+
+## API
+
+```ts
+import { start } from "@ithousecall/chat";
+import jira from "./extensions/jira.ts";
+
+await start({ config: "config/config.yaml", data: "data", extensions: [jira] });
+```
+
+- `start({ config, data, extensions? })` starts @housecall and returns once it is up; on SIGINT or SIGTERM it shuts down
+  and exits the process. `config` and `data` are resolved against the working directory, and so are relative paths
+  inside the config file. `--console` on the command line selects the console adapter. If @housecall cannot start, for
+  example on a config error or when another process uses `data`, it prints `@housecall cannot start:` with the reason and
+  exits with status 1.
+- `defineExtension({ name, tools })` and `defineTool({ name, description, parameters, execute, write?, summary? })`
+  define tools. `write: true` makes the requester confirm each call in chat before `execute` runs.
+- `requester(api, context)` returns the chat user whose message led to the tool call.
+- `Type` builds tool parameter schemas.
+- Types: `StartOptions`, `ChatUser`, `Extension`, `AgentTool`, `ToolExecutionApi`, `ToolExecutionResult`.
+
+## Attachments
+
+Images people post (Slack files, Teams pasted images and personal-chat uploads, Google Chat uploads) are downloaded
+during the turn and sent to the model with the message: PNG, JPEG, GIF and WebP, at most 10 MB and 25 megapixels
+each, at most 4 per turn. Each is resized with pi-durable's Photon processor to at most 1568 px on its long edge and
+1 MB, or the model's own image limits if smaller. When @housecall is mentioned in a Slack or Google Chat thread, the
+images its author posted in the thread since @housecall last replied are read too, newest first, within the same 4.
+Images posted by others show as `[image]` in the thread history.
+
+Images are stored in the conversation in `<data>/session.sqlite`; nothing else is written to disk. Each request to the
+model carries only the images of the newest message; earlier images are replaced by `[image]`, so later answers rely on
+what the model said about them. A thread's messages are taken in the order they arrive, so a message sent while an
+earlier one's images download waits for it.
+
+Other files are named to the model but not read. A skipped or unreadable image gets a note to the model and, unless it
+was over 10 MB or past the fourth, a log line `[attachments] <platform> <file>: <problem>`. A model without image input
+(`model.images: false` for `openai_compatible`, or a catalog model without it) is told how many images it cannot see,
+and nothing is downloaded.
+
+## Development
+
+```sh
+npm ci
+npm run ci      # type check, lint, tests
+npm run build   # dist/
+```
+
+To run a starter against this checkout, build here and run `npm install ../package` in `chat_agent/starter`.
+Don't commit the starter's `package.json` or lockfile after `npm install ../package`.

package/dist/attachments.d.ts

@@ -0,0 +1,32 @@
+import type { ImageContent, Message, TextContent } from "@earendil-works/pi-ai";
+import type { ImageLimits, ImageProcessor } from "@earendil-works/pi-durable/tools";
+import type { ChatAdapter, InboundMessage } from "./chat/adapter.ts";
+/** How images are prepared for the model; undefined when the model cannot see them. */
+export type ImageOptions = {
+    processor: ImageProcessor;
+    limits: ImageLimits;
+};
+/** What earlier thread messages show of their attachments. */
+export declare function attachmentMarks(message: InboundMessage): string;
+type ImageHeader = {
+    mimeType: string;
+    width: number;
+    height: number;
+};
+/** The format and declared size of a PNG, JPEG, GIF or WebP, read from its header without decoding it. */
+export declare function imageHeader(bytes: Uint8Array): ImageHeader | undefined;
+/**
+ * The model's view of a message's attachments, and of the images its author posted in `earlier` thread messages, newest
+ * first: images downloaded and prepared for the model; a note for every file it does not get.
+ */
+export declare function readAttachments(adapter: ChatAdapter, message: InboundMessage, earlier: readonly InboundMessage[], prepare: ImageOptions | undefined, signal: AbortSignal): Promise<{
+    notes: string[];
+    images: ImageContent[];
+}>;
+export declare function inputContent(text: string, read: {
+    notes: string[];
+    images: ImageContent[];
+}): string | (TextContent | ImageContent)[];
+/** What a request sends: images before the newest user message become `[image]`, so a thread's images are sent once. */
+export declare function olderImagesHidden(messages: readonly Message[]): Message[];
+export {};

package/dist/attachments.js

@@ -0,0 +1,159 @@
+import { MAX_ATTACHMENT_BYTES } from "./chat/adapter.js";
+import { TooLarge } from "./chat/download.js";
+const MAX_IMAGES = 4;
+/** Photon decodes the whole bitmap, 4 bytes a pixel, before it shrinks it. */
+const MAX_PIXELS = 25_000_000;
+function isImage(attachment) {
+    return attachment.mimeType.startsWith("image/");
+}
+/** What earlier thread messages show of their attachments. */
+export function attachmentMarks(message) {
+    return message.attachments
+        .map((attachment) => (isImage(attachment) ? " [image]" : ` [file ${attachment.name}]`))
+        .join("");
+}
+/** The format and declared size of a PNG, JPEG, GIF or WebP, read from its header without decoding it. */
+export function imageHeader(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const ascii = (start, end) => String.fromCharCode(...bytes.subarray(start, end));
+    try {
+        if (ascii(1, 4) === "PNG")
+            return { mimeType: "image/png", width: view.getUint32(16), height: view.getUint32(20) };
+        if (ascii(0, 4) === "GIF8") {
+            return { mimeType: "image/gif", width: view.getUint16(6, true), height: view.getUint16(8, true) };
+        }
+        if (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP") {
+            const mimeType = "image/webp";
+            switch (ascii(12, 16)) {
+                case "VP8 ":
+                    return { mimeType, width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+                case "VP8L": {
+                    const bits = view.getUint32(21, true);
+                    return { mimeType, width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+                }
+                case "VP8X":
+                    return {
+                        mimeType,
+                        width: (view.getUint32(24, true) & 0xffffff) + 1,
+                        height: (view.getUint32(27, true) & 0xffffff) + 1,
+                    };
+                default:
+                    return undefined;
+            }
+        }
+        if (bytes[0] !== 0xff || bytes[1] !== 0xd8)
+            return undefined;
+        for (let offset = 2; offset < bytes.length;) {
+            if (bytes[offset] !== 0xff)
+                return undefined;
+            const marker = view.getUint8(offset + 1);
+            if (marker === 0xff) {
+                offset++;
+                continue;
+            }
+            // SOF0 to SOF15, except DHT (C4), JPG (C8) and DAC (CC), which share the range.
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { mimeType: "image/jpeg", width: view.getUint16(offset + 7), height: view.getUint16(offset + 5) };
+            }
+            offset += 2 + view.getUint16(offset + 2);
+        }
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The model's view of a message's attachments, and of the images its author posted in `earlier` thread messages, newest
+ * first: images downloaded and prepared for the model; a note for every file it does not get.
+ */
+export async function readAttachments(adapter, message, earlier, prepare, signal) {
+    const notes = [];
+    const images = [];
+    const posted = earlier
+        .filter((other) => other.user.id === message.user.id)
+        .reverse()
+        .flatMap((other) => other.attachments.filter(isImage));
+    const attached = [...message.attachments.filter(isImage), ...posted];
+    const log = (file, problem) => console.error(`[attachments] ${message.platform} ${file.name}: ${problem}`);
+    for (const file of message.attachments)
+        if (!isImage(file))
+            notes.push(`(attached file ${file.name} was not read)`);
+    if (attached.length === 0)
+        return { notes, images };
+    if (prepare === undefined) {
+        const what = attached.length === 1 ? "an image" : `${attached.length} images`;
+        notes.push(`(The user attached ${what} you cannot see. Ask them to describe what it shows if it matters.)`);
+        return { notes, images };
+    }
+    let tried = 0;
+    for (const file of attached) {
+        const tooLarge = `(attached image ${file.name} was skipped: larger than ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB)`;
+        if ((file.size ?? 0) > MAX_ATTACHMENT_BYTES) {
+            notes.push(tooLarge);
+            continue;
+        }
+        if (tried++ >= MAX_IMAGES) {
+            notes.push(`(attached image ${file.name} was skipped: at most ${MAX_IMAGES} images are read at a time)`);
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = await adapter.download(file, signal);
+        }
+        catch (error) {
+            if (!(error instanceof TooLarge))
+                log(file, String(error));
+            notes.push(error instanceof TooLarge ? tooLarge : `(attached image ${file.name} could not be downloaded)`);
+            continue;
+        }
+        const header = imageHeader(bytes);
+        if (header === undefined) {
+            log(file, "not a PNG, JPEG, GIF or WebP image");
+            notes.push(`(attached image ${file.name} could not be read)`);
+            continue;
+        }
+        if (header.width * header.height > MAX_PIXELS) {
+            log(file, `${header.width}x${header.height} is over ${MAX_PIXELS} pixels`);
+            notes.push(`(attached image ${file.name} was skipped: larger than ${MAX_PIXELS / 1_000_000} megapixels)`);
+            continue;
+        }
+        const prepared = await prepare.processor.prepare(bytes, header.mimeType, prepare.limits).catch(() => undefined);
+        if (prepared === undefined) {
+            log(file, "could not be decoded");
+            notes.push(`(attached image ${file.name} could not be read)`);
+        }
+        else {
+            images.push({ type: "image", data: prepared.data, mimeType: prepared.mimeType });
+        }
+    }
+    return { notes, images };
+}
+export function inputContent(text, read) {
+    const full = [text, read.notes.join("\n")].filter((part) => part !== "").join("\n\n");
+    if (read.images.length === 0)
+        return full;
+    return [...(full === "" ? [] : [{ type: "text", text: full }]), ...read.images];
+}
+const hidden = (block) => block.type === "image" ? { type: "text", text: "[image]" } : block;
+/** What a request sends: images before the newest user message become `[image]`, so a thread's images are sent once. */
+export function olderImagesHidden(messages) {
+    const newest = messages.findLastIndex((message) => message.role === "user");
+    return messages.map((message, index) => {
+        if (index >= newest)
+            return message;
+        switch (message.role) {
+            case "user":
+                return typeof message.content === "string" ? message : { ...message, content: message.content.map(hidden) };
+            case "toolResult":
+                return { ...message, content: message.content.map(hidden) };
+            case "system":
+            case "assistant":
+                return message;
+            default:
+                throw new Error(`unknown message role ${JSON.stringify(message)}`);
+        }
+    });
+}

package/dist/chat/adapter.d.ts

@@ -0,0 +1,77 @@
+import type { JsonObject } from "@earendil-works/pi-durable";
+export type Platform = "slack" | "teams" | "googlechat" | "console";
+export type ThreadRef = {
+    platform: Platform;
+    spaceId: string;
+    threadId: string;
+};
+export type MessageRef = ThreadRef & {
+    messageId: string;
+};
+export type ChatUser = {
+    id: string;
+    name?: string;
+};
+/** A file on an inbound message. `source` is what the adapter fetches it from: a URL or an API resource name. */
+export type Attachment = {
+    name: string;
+    mimeType: string;
+    size?: number;
+    source: string;
+};
+/** Downloads stop at this many bytes. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+export type InboundMessage = ThreadRef & {
+    messageId: string;
+    user: ChatUser;
+    text: string;
+    attachments: Attachment[];
+    isDirect: boolean;
+    mentionsBot: boolean;
+    /** Orders messages within a thread; compared as strings. */
+    cursor: string;
+};
+export type ApprovalPrompt = {
+    approvalId: string;
+    tool: string;
+    summary: string;
+    args: JsonObject;
+    requester: ChatUser;
+};
+export type Decision = "approve" | "deny";
+export type ApprovalOutcome = "approved" | "denied" | "expired";
+export type ApprovalDecision = {
+    approvalId: string;
+    decision: Decision;
+    user: ChatUser;
+};
+/** What the person who clicked is told; `counted` when their click decided the approval. */
+export type ApprovalFeedback = {
+    counted: boolean;
+    text: string;
+};
+export interface AdapterHandlers {
+    onMessage(message: InboundMessage): Promise<void>;
+    onApproval(decision: ApprovalDecision): Promise<ApprovalFeedback>;
+}
+export interface ChatAdapter {
+    readonly platform: Platform;
+    readonly maxMessageLength: number;
+    start(handlers: AdapterHandlers): Promise<void>;
+    stop(): Promise<void>;
+    post(thread: ThreadRef, markdown: string): Promise<MessageRef>;
+    update(ref: MessageRef, markdown: string): Promise<void>;
+    remove(ref: MessageRef): Promise<void>;
+    postApproval(thread: ThreadRef, prompt: ApprovalPrompt): Promise<MessageRef>;
+    resolveApprovalMessage(ref: MessageRef, prompt: ApprovalPrompt, outcome: ApprovalOutcome, by?: ChatUser): Promise<void>;
+    /**
+     * The attachment's bytes, at most MAX_ATTACHMENT_BYTES, in a Uint8Array of their own: the image worker cannot take
+     * a Buffer from Node's shared pool.
+     */
+    download(attachment: Attachment, signal: AbortSignal): Promise<Uint8Array>;
+    /** Thread messages after `after`, oldest first; [] where the platform offers no history. */
+    fetchThread(thread: ThreadRef, after: string | undefined): Promise<InboundMessage[]>;
+}
+export declare function messageRef(thread: ThreadRef, messageId: string): MessageRef;
+export declare function approvalArgs(prompt: ApprovalPrompt): string;
+export declare function decisionText(prompt: ApprovalPrompt, outcome: ApprovalOutcome, by: ChatUser | undefined): string;

package/dist/chat/adapter.js

@@ -0,0 +1,23 @@
+/** Downloads stop at this many bytes. */
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export function messageRef(thread, messageId) {
+    return { platform: thread.platform, spaceId: thread.spaceId, threadId: thread.threadId, messageId };
+}
+const MAX_APPROVAL_ARGS = 1000;
+export function approvalArgs(prompt) {
+    const args = JSON.stringify(prompt.args);
+    return args.length > MAX_APPROVAL_ARGS ? `${args.slice(0, MAX_APPROVAL_ARGS)}…` : args;
+}
+export function decisionText(prompt, outcome, by) {
+    const who = by?.name ?? by?.id;
+    switch (outcome) {
+        case "approved":
+            return `Approved${who === undefined ? "" : ` by ${who}`}: ${prompt.summary}`;
+        case "denied":
+            return `Denied${who === undefined ? "" : ` by ${who}`}: ${prompt.summary}`;
+        case "expired":
+            return `Expired without a decision: ${prompt.summary}`;
+        default:
+            throw new Error(`unknown approval outcome ${JSON.stringify(outcome)}`);
+    }
+}

package/dist/chat/console.d.ts

@@ -0,0 +1,21 @@
+import { type AdapterHandlers, type ApprovalOutcome, type ApprovalPrompt, type Attachment, type ChatAdapter, type ChatUser, type InboundMessage, type MessageRef, type ThreadRef } from "./adapter.ts";
+/**
+ * stdin/stdout chat, for trying housecall without a chat platform. One thread; `approve <id>` / `deny <id>` decide, and
+ * `/image <path> [message]` attaches a local file.
+ */
+export declare class ConsoleAdapter implements ChatAdapter {
+    #private;
+    readonly platform = "console";
+    readonly maxMessageLength = 100000;
+    /** Resolves once stdin has closed and every message read from it has been handled. */
+    readonly ended: Promise<void>;
+    start(handlers: AdapterHandlers): Promise<void>;
+    stop(): Promise<void>;
+    post(thread: ThreadRef, markdown: string): Promise<MessageRef>;
+    update(ref: MessageRef, markdown: string): Promise<void>;
+    remove(ref: MessageRef): Promise<void>;
+    postApproval(thread: ThreadRef, prompt: ApprovalPrompt): Promise<MessageRef>;
+    resolveApprovalMessage(ref: MessageRef, prompt: ApprovalPrompt, outcome: ApprovalOutcome, by?: ChatUser): Promise<void>;
+    download(attachment: Attachment, signal: AbortSignal): Promise<Uint8Array>;
+    fetchThread(): Promise<InboundMessage[]>;
+}

package/dist/chat/console.js

@@ -0,0 +1,105 @@
+import { open } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { basename } from "node:path";
+import { createInterface } from "node:readline";
+import { approvalArgs, decisionText, messageRef, } from "./adapter.js";
+import { readCapped } from "./download.js";
+const THREAD = { platform: "console", spaceId: "console", threadId: "main" };
+function parseConsoleLine(line, user, messageId) {
+    const text = line.trim();
+    if (text === "")
+        return undefined;
+    const decision = /^(approve|deny)\s+(\S+)$/i.exec(text);
+    if (decision?.[1] !== undefined && decision[2] !== undefined) {
+        return { approvalId: decision[2], decision: decision[1].toLowerCase() === "approve" ? "approve" : "deny", user };
+    }
+    const image = /^\/image\s+(\S+)\s*(.*)$/.exec(text);
+    const path = image?.[1];
+    const attachments = path === undefined ? [] : [{ name: basename(path), mimeType: "image/*", source: path }];
+    return {
+        ...THREAD,
+        messageId,
+        user,
+        text: image === null ? text : (image[2] ?? ""),
+        attachments,
+        isDirect: true,
+        mentionsBot: false,
+        cursor: messageId,
+    };
+}
+/**
+ * stdin/stdout chat, for trying housecall without a chat platform. One thread; `approve <id>` / `deny <id>` decide, and
+ * `/image <path> [message]` attaches a local file.
+ */
+export class ConsoleAdapter {
+    platform = "console";
+    maxMessageLength = 100_000;
+    #user = { id: "console", name: userInfo().username };
+    #shown = new Map();
+    #handling = new Set();
+    #readline;
+    #next = 0;
+    #ended = () => undefined;
+    /** Resolves once stdin has closed and every message read from it has been handled. */
+    ended = new Promise((resolve) => {
+        this.#ended = resolve;
+    });
+    async start(handlers) {
+        this.#readline = createInterface({ input: process.stdin, terminal: false });
+        this.#readline.on("line", (line) => {
+            const parsed = parseConsoleLine(line, this.#user, `${Date.now()}-${this.#next++}`);
+            if (parsed === undefined)
+                return;
+            const handled = ("approvalId" in parsed
+                ? handlers.onApproval(parsed).then((feedback) => {
+                    if (!feedback.counted)
+                        console.log(feedback.text);
+                })
+                : handlers.onMessage(parsed)).catch((error) => console.error(error));
+            this.#handling.add(handled);
+            void handled.finally(() => this.#handling.delete(handled));
+        });
+        this.#readline.on("close", () => {
+            void Promise.all(this.#handling).then(() => this.#ended());
+        });
+        console.log('@housecall console. Ask a question; answer approval prompts with "approve <id>" or "deny <id>"; attach a file with "/image <path> [message]".');
+    }
+    async stop() {
+        this.#readline?.close();
+    }
+    #print(ref, text) {
+        if (this.#shown.get(ref.messageId) === text)
+            return;
+        this.#shown.set(ref.messageId, text);
+        console.log(`\n@housecall [${ref.messageId}]> ${text.replaceAll("\n", "\n  ")}`);
+    }
+    async post(thread, markdown) {
+        const ref = messageRef(thread, `m${this.#next++}`);
+        this.#print(ref, markdown);
+        return ref;
+    }
+    async update(ref, markdown) {
+        this.#print(ref, markdown);
+    }
+    async remove(ref) {
+        this.#shown.delete(ref.messageId);
+    }
+    async postApproval(thread, prompt) {
+        return this.post(thread, `Approval needed: ${prompt.summary}\n${prompt.tool} ${approvalArgs(prompt)}\nType "approve ${prompt.approvalId}" or "deny ${prompt.approvalId}".`);
+    }
+    async resolveApprovalMessage(ref, prompt, outcome, by) {
+        this.#print(ref, decisionText(prompt, outcome, by));
+    }
+    async download(attachment, signal) {
+        const file = await open(attachment.source);
+        try {
+            return await readCapped(file.createReadStream({ autoClose: false, signal }));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async fetchThread() {
+        return [];
+    }
+}

package/dist/chat/download.d.ts

@@ -0,0 +1,13 @@
+export declare class TooLarge extends Error {
+}
+/** The body, failing once it passes `maxBytes`. */
+export declare function readCapped(body: AsyncIterable<Uint8Array>, maxBytes?: number): Promise<Uint8Array>;
+/**
+ * GETs an HTTPS URL into memory, at most `maxBytes`. Redirects are followed by hand so `headers`, which may carry a
+ * token, go only to the first URL's origin.
+ */
+export declare function fetchCapped(url: string, options: {
+    headers?: Record<string, string>;
+    signal: AbortSignal;
+    maxBytes?: number;
+}): Promise<Uint8Array>;

package/dist/chat/download.js

@@ -0,0 +1,61 @@
+import { MAX_ATTACHMENT_BYTES } from "./adapter.js";
+const MAX_REDIRECTS = 5;
+export class TooLarge extends Error {
+}
+/** The body, failing once it passes `maxBytes`. */
+export async function readCapped(body, maxBytes = MAX_ATTACHMENT_BYTES) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        total += chunk.byteLength;
+        if (total > maxBytes)
+            throw new TooLarge(`larger than ${maxBytes} bytes`);
+        chunks.push(chunk);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+/**
+ * GETs an HTTPS URL into memory, at most `maxBytes`. Redirects are followed by hand so `headers`, which may carry a
+ * token, go only to the first URL's origin.
+ */
+export async function fetchCapped(url, options) {
+    const origin = new URL(url).origin;
+    let next = new URL(url);
+    for (let redirects = 0;; redirects++) {
+        if (next.protocol !== "https:")
+            throw new Error(`refusing to fetch ${next.protocol} URL`);
+        const response = await fetch(next, {
+            redirect: "manual",
+            signal: options.signal,
+            ...(next.origin === origin && options.headers !== undefined ? { headers: options.headers } : {}),
+        });
+        const location = response.headers.get("location");
+        if (response.status >= 300 && response.status < 400 && location !== null) {
+            await response.body?.cancel();
+            if (redirects >= MAX_REDIRECTS)
+                throw new Error("too many redirects");
+            next = new URL(location, next);
+            continue;
+        }
+        if (!response.ok || response.body === null) {
+            await response.body?.cancel();
+            throw new Error(`${next.origin}${next.pathname} answered ${response.status}`);
+        }
+        if (response.headers.get("content-type")?.startsWith("text/html") === true) {
+            await response.body.cancel();
+            throw new Error(`${next.origin}${next.pathname} answered with a web page, not the file`);
+        }
+        const maxBytes = options.maxBytes ?? MAX_ATTACHMENT_BYTES;
+        if (Number(response.headers.get("content-length") ?? 0) > maxBytes) {
+            await response.body.cancel();
+            throw new TooLarge(`larger than ${maxBytes} bytes`);
+        }
+        return readCapped(response.body, maxBytes);
+    }
+}

package/dist/chat/googlechat.d.ts

@@ -0,0 +1,54 @@
+import { type chat_v1 } from "@googleapis/chat";
+import { type Certificates } from "google-auth-library";
+import type { Hono } from "hono";
+import { type AdapterHandlers, type ApprovalDecision, type ApprovalOutcome, type ApprovalPrompt, type Attachment, type ChatAdapter, type ChatUser, type InboundMessage, type MessageRef, type ThreadRef } from "./adapter.ts";
+/** The thread ID of a DM's top level: one conversation per DM, answered without a thread. */
+export declare const DM_TOP_LEVEL = "dm";
+type GoogleChatEvent = {
+    kind: "message";
+    message: InboundMessage;
+} | {
+    kind: "approval";
+    decision: ApprovalDecision;
+    addOn: boolean;
+} | {
+    kind: "ignored";
+};
+export declare function normalizeGoogleChatEvent(body: unknown): GoogleChatEvent;
+type CertificateSource = (url: string) => Promise<Certificates>;
+/**
+ * Accepts only this project's requests: a Chat API app with the "Project Number" authentication audience gets a JWT
+ * from Chat for the project number; a Workspace add-on Chat app gets a Google ID token for the endpoint URL from the
+ * project's own add-on service agent.
+ */
+export declare function googleTokenVerifier(projectNumber: string, endpointUrl: string, certificates?: CertificateSource): (authorization: string | undefined) => Promise<boolean>;
+/** The Chat API calls the adapter makes, so it can be tested without Google. */
+export interface GoogleChatApi {
+    create(parent: string, message: chat_v1.Schema$Message, threaded: boolean): Promise<string>;
+    patch(name: string, message: chat_v1.Schema$Message, updateMask: string): Promise<void>;
+    remove(name: string): Promise<void>;
+    list(parent: string, filter: string): Promise<unknown[]>;
+    download(resourceName: string, signal: AbortSignal): Promise<Uint8Array>;
+}
+/**
+ * Listing messages needs chat.app.messages.readonly, which an admin must grant, so it has its own client and posting
+ * keeps working without it.
+ */
+export declare function googleChatApi(keyFile: string): GoogleChatApi;
+/** Google Chat as an HTTP endpoint app: Google posts events to `endpointUrl`; replies go out through the Chat API. */
+export declare class GoogleChatAdapter implements ChatAdapter {
+    #private;
+    readonly platform = "googlechat";
+    readonly maxMessageLength = 4000;
+    constructor(http: Hono, endpointUrl: string, api: GoogleChatApi, verify: (authorization: string | undefined) => Promise<boolean>);
+    start(handlers: AdapterHandlers): Promise<void>;
+    stop(): Promise<void>;
+    post(thread: ThreadRef, markdown: string): Promise<MessageRef>;
+    update(ref: MessageRef, markdown: string): Promise<void>;
+    remove(ref: MessageRef): Promise<void>;
+    postApproval(thread: ThreadRef, prompt: ApprovalPrompt): Promise<MessageRef>;
+    resolveApprovalMessage(ref: MessageRef, prompt: ApprovalPrompt, outcome: ApprovalOutcome, by?: ChatUser): Promise<void>;
+    download(attachment: Attachment, signal: AbortSignal): Promise<Uint8Array>;
+    fetchThread(thread: ThreadRef, after: string | undefined): Promise<InboundMessage[]>;
+}
+export {};