@ithousecall/chat 0.0.0-stage → 0.2.1

package/dist/start.js

@@ -0,0 +1,148 @@
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createRegistry } from "@earendil-works/pi-durable";
+import { createNodePhotonImages } from "@earendil-works/pi-durable/images/node";
+import { ConsoleAdapter } from "./chat/console.js";
+import { GoogleChatAdapter, googleChatApi, googleTokenVerifier } from "./chat/googlechat.js";
+import { HttpServer } from "./chat/http.js";
+import { SlackAdapter } from "./chat/slack.js";
+import { TeamsAdapter } from "./chat/teams.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { confluenceSource } from "./docs/confluence.js";
+import { driveSource, googleDriveApi } from "./docs/drive.js";
+import { DocsIndex } from "./docs/index.js";
+import { localSource } from "./docs/local.js";
+import { startDocsSync } from "./docs/sync.js";
+import { docsExtension } from "./docs/tools.js";
+import { setApprovalTransport } from "./extensions/approvals.js";
+import { startMcp } from "./extensions/mcp.js";
+import { context, openHarness } from "./harness.js";
+import { acquireLock } from "./lock.js";
+import { createModelSetup, modelKeyEnv } from "./model.js";
+import { PromptExtension } from "./prompt.js";
+import { turnRunner } from "./turn.js";
+function docsSource(source) {
+    switch (source.type) {
+        case "local":
+            return localSource(source.name, source.path, source.url_base);
+        case "google_drive": {
+            const [keyFile = ""] = requireEnv("GOOGLE_SERVICE_ACCOUNT_FILE");
+            return driveSource(source.name, source.folder_id, googleDriveApi(keyFile));
+        }
+        case "confluence": {
+            const [email = "", apiToken = ""] = requireEnv("CONFLUENCE_EMAIL", "CONFLUENCE_API_TOKEN");
+            const scope = {
+                site: source.site,
+                ...(source.space_key === undefined ? {} : { spaceKey: source.space_key }),
+                ...(source.parent_page_id === undefined ? {} : { parentPageId: source.parent_page_id }),
+            };
+            return confluenceSource(source.name, scope, { email, apiToken });
+        }
+        default:
+            throw new ConfigError(`docs.sources: unknown type ${JSON.stringify(source)}`);
+    }
+}
+function requireEnv(...names) {
+    const missing = names.filter((name) => (process.env[name] ?? "") === "");
+    if (missing.length > 0)
+        throw new ConfigError(`environment: set ${missing.join(", ")} in .env`);
+    return names.map((name) => process.env[name] ?? "");
+}
+/** Checks each enabled platform's secrets now; the adapters are built once the harness is open. */
+function chatAdapters(config, consoleMode) {
+    if (consoleMode)
+        return [() => new ConsoleAdapter()];
+    const factories = [];
+    if (config.chat.slack.enabled) {
+        const [botToken = "", appToken = ""] = requireEnv("SLACK_BOT_TOKEN", "SLACK_APP_TOKEN");
+        factories.push(() => new SlackAdapter(botToken, appToken));
+    }
+    if (config.chat.teams.enabled) {
+        const [clientId = "", clientSecret = "", tenantId = ""] = requireEnv("TEAMS_CLIENT_ID", "TEAMS_CLIENT_SECRET", "TEAMS_TENANT_ID");
+        factories.push((http) => new TeamsAdapter(http.app, { clientId, clientSecret, tenantId }));
+    }
+    const { enabled, endpoint_url: endpointUrl, project_number: projectNumber } = config.chat.googlechat;
+    if (enabled && endpointUrl !== undefined && projectNumber !== undefined) {
+        const [keyFile = ""] = requireEnv("GOOGLE_SERVICE_ACCOUNT_FILE");
+        const verify = googleTokenVerifier(projectNumber, endpointUrl);
+        factories.push((http) => new GoogleChatAdapter(http.app, endpointUrl, googleChatApi(keyFile), verify));
+    }
+    if (factories.length === 0) {
+        throw new ConfigError("chat: no chat platform is enabled; enable one in config.yaml or run `npm run console`");
+    }
+    return factories;
+}
+async function run(options) {
+    const config = loadConfig(resolve(options.config));
+    const dataDir = resolve(options.data);
+    requireEnv(modelKeyEnv(config.model));
+    const modelSetup = createModelSetup(config.model);
+    const adapterFactories = chatAdapters(config, process.argv.includes("--console"));
+    const sources = config.docs.sources.map(docsSource);
+    mkdirSync(dataDir, { recursive: true });
+    const releaseLock = acquireLock(dataDir);
+    const index = new DocsIndex(join(dataDir, "docs.sqlite"));
+    const registry = createRegistry();
+    registry.install(PromptExtension);
+    registry.install(docsExtension(index));
+    for (const extension of options.extensions ?? [])
+        registry.install(extension);
+    const stopMcp = startMcp(registry, config.mcp);
+    const harness = await openHarness(join(dataDir, "session.sqlite"), modelSetup.models, registry);
+    const http = new HttpServer();
+    const adapters = adapterFactories.map((create) => create(http));
+    const byPlatform = new Map(adapters.map((adapter) => [adapter.platform, adapter]));
+    setApprovalTransport({ adapters: byPlatform, timeoutMs: config.approvals.timeout_minutes * 60_000 });
+    const { imageLimits } = modelSetup;
+    const runner = turnRunner(harness, {
+        model: modelSetup.model,
+        ...(config.system_prompt === undefined ? {} : { instructions: config.system_prompt }),
+    }, imageLimits === undefined ? undefined : { processor: await createNodePhotonImages(), limits: imageLimits });
+    const stopSync = startDocsSync(index, sources, config.docs.sync_interval_minutes);
+    let stopping;
+    const shutdown = () => {
+        stopping ??= (async () => {
+            await Promise.allSettled(adapters.map((adapter) => adapter.stop()));
+            await http.stop();
+            await stopSync();
+            await stopMcp();
+            await harness.close(context);
+            index.close();
+            releaseLock();
+            process.exit(0);
+        })();
+        return stopping;
+    };
+    process.once("SIGINT", () => void shutdown());
+    process.once("SIGTERM", () => void shutdown());
+    void harness.closed.then((end) => {
+        if (end.reason === "failed") {
+            console.error("[harness] storage failed; exiting so the process restarts", end.error);
+            process.exit(1);
+        }
+    });
+    await Promise.all(adapters.map((adapter) => adapter.start(runner.handlers(adapter))));
+    if (adapters.some((adapter) => adapter.platform === "teams" || adapter.platform === "googlechat")) {
+        await http.start(config.http.port);
+        console.log(`[housecall] listening on :${config.http.port}`);
+    }
+    harness.resume();
+    void runner.resume(byPlatform);
+    for (const adapter of adapters)
+        if (adapter instanceof ConsoleAdapter)
+            void adapter.ended.then(shutdown);
+    console.log(`[housecall] up: ${adapters.map((adapter) => adapter.platform).join(", ")}`);
+}
+/**
+ * Starts @housecall and returns once it is up; on SIGINT or SIGTERM it shuts down and exits the process. `--console` in
+ * process.argv selects the console adapter.
+ */
+export async function start(options) {
+    try {
+        await run(options);
+    }
+    catch (error) {
+        console.error(error instanceof ConfigError ? `@housecall cannot start:\n${error.message}` : error);
+        process.exit(1);
+    }
+}

package/dist/threads.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from "@earendil-works/chord";
+import { type Conversation, type Harness, type ModelRef, type ToolExecutionApi } from "@earendil-works/pi-durable";
+import type { ChatUser, ThreadRef } from "./chat/adapter.ts";
+export type AgentChoice = {
+    model: ModelRef;
+    instructions?: string;
+};
+/** The chat thread a conversation answers: tools find where to ask for approval here. */
+export declare const ThreadDoc: import("@earendil-works/pi-durable").ConversationDocToken<ThreadRef>;
+/** Each chat message is placed in the transcript as this entry, with its author as data. */
+export declare const ChatMessageEntry: import("@earendil-works/pi-durable").Entry<ChatUser>;
+/**
+ * The author of the newest chat message the model has seen: the person a tool acts for. Steered messages are placed
+ * only after the running tool round, so during a tool call this is the author of the input that led to it.
+ */
+export declare function requester(api: ToolExecutionApi, ctx: Context): Promise<ChatUser | undefined>;
+export declare function openThread(harness: Harness, thread: ThreadRef, agent: AgentChoice): Promise<Conversation>;
+export declare function lastSeenCursor(harness: Harness, thread: ThreadRef): Promise<string | undefined>;
+export declare function markThreadSeen(harness: Harness, thread: ThreadRef, cursor: string): Promise<void>;

package/dist/threads.js

@@ -0,0 +1,73 @@
+import { configure, defineDoc, defineEntry, defineDocFamily, } from "@earendil-works/pi-durable";
+import { context } from "./harness.js";
+const Threads = defineDocFamily({
+    kind: "app.threads",
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: () => ({ conversationId: 0, lastSeenCursor: "" }),
+    checkpointWhen: () => true,
+});
+/** The chat thread a conversation answers: tools find where to ask for approval here. */
+export const ThreadDoc = defineDoc({
+    kind: "app.thread",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "current",
+    initial: () => ({ platform: "console", spaceId: "", threadId: "" }),
+    checkpointWhen: () => true,
+});
+/** Each chat message is placed in the transcript as this entry, with its author as data. */
+export const ChatMessageEntry = defineEntry("app.chat_message");
+/**
+ * The author of the newest chat message the model has seen: the person a tool acts for. Steered messages are placed
+ * only after the running tool round, so during a tool call this is the author of the input that led to it.
+ */
+export async function requester(api, ctx) {
+    return api.commit(async (tx) => {
+        let cursor;
+        do {
+            const page = await tx.scanEntries({ conversationId: api.conversationId, order: "descending" }, 50, cursor);
+            for (const entry of page.items)
+                if (ChatMessageEntry.is(entry))
+                    return entry.data;
+            cursor = page.next;
+        } while (cursor !== undefined);
+        return undefined;
+    }, ctx);
+}
+function threadKey(thread) {
+    return `${thread.platform}:${thread.spaceId}:${thread.threadId}`;
+}
+export async function openThread(harness, thread, agent) {
+    const id = await harness.commit(async (tx) => {
+        const mapping = await tx.doc(Threads, threadKey(thread), null);
+        let conversationId = mapping.conversationId;
+        if (mapping.conversationId === 0) {
+            conversationId = (await tx.createConversation({ ownership: { kind: "ownerless" } })).id;
+            mapping.conversationId = conversationId;
+        }
+        await configure(tx, conversationId, { model: agent.model, instructions: agent.instructions ?? null });
+        const info = await tx.doc(ThreadDoc, conversationId);
+        info.platform = thread.platform;
+        info.spaceId = thread.spaceId;
+        info.threadId = thread.threadId;
+        return conversationId;
+    }, context);
+    const conversation = await harness.conversation(id, context);
+    if (conversation === undefined)
+        throw new Error(`conversation ${id} missing after commit`);
+    return conversation;
+}
+export async function lastSeenCursor(harness, thread) {
+    const mapping = await harness.snapshot(Threads, threadKey(thread), context);
+    return mapping?.lastSeenCursor === "" ? undefined : mapping?.lastSeenCursor;
+}
+export async function markThreadSeen(harness, thread, cursor) {
+    await harness.commit(async (tx) => {
+        const mapping = await tx.doc(Threads, threadKey(thread), null);
+        if (cursor > mapping.lastSeenCursor)
+            mapping.lastSeenCursor = cursor;
+    }, context);
+}

package/dist/turn.d.ts

@@ -0,0 +1,12 @@
+import { type Harness } from "@earendil-works/pi-durable";
+import { type ImageOptions } from "./attachments.ts";
+import type { AdapterHandlers, ChatAdapter, InboundMessage, Platform } from "./chat/adapter.ts";
+import { type AgentChoice } from "./threads.ts";
+type TurnRunner = {
+    run(adapter: ChatAdapter, message: InboundMessage): Promise<void>;
+    resume(adapters: ReadonlyMap<Platform, ChatAdapter>): Promise<void>;
+    /** What an adapter calls: DMs and mentions start turns, button clicks decide approvals. */
+    handlers(adapter: ChatAdapter): AdapterHandlers;
+};
+export declare function turnRunner(harness: Harness, agent: AgentChoice, images: ImageOptions | undefined): TurnRunner;
+export {};

package/dist/turn.js

@@ -0,0 +1,206 @@
+import { AssistantEntry, defineDoc, LiveDoc, } from "@earendil-works/pi-durable";
+import { attachmentMarks, inputContent, readAttachments } from "./attachments.js";
+import { resolveApproval } from "./extensions/approvals.js";
+import { answerText, chunkText, liveStatusText, PLACEHOLDER } from "./format.js";
+import { context } from "./harness.js";
+import { ChatMessageEntry, lastSeenCursor, markThreadSeen, openThread } from "./threads.js";
+/** Turns whose answer has not been posted yet, keyed by request ID; a restart finishes them. */
+const Turns = defineDoc({
+    kind: "app.turns",
+    version: 1,
+    scope: "session",
+    initial: () => ({ pending: {} }),
+    checkpointWhen: () => true,
+});
+const BLANK_MESSAGE = "(The user mentioned you without a message. Read the thread and help with what they need.)";
+const RESTARTED = "I restarted before I could read this. Please send it again.";
+const STATUS_INTERVAL_MS = 1200;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+export function turnRunner(harness, agent, images) {
+    const inFlight = new Set();
+    /**
+     * One run answers every input steered into it; the first of their turns posts the answer. Kept per conversation
+     * until none of its turns is finishing.
+     */
+    const posted = new Map();
+    const finishing = new Map();
+    const admitting = new Map();
+    let closing = false;
+    harness.subscribeClose(() => {
+        closing = true;
+    });
+    const admitted = (conversation, requestId) => conversation.commit((tx) => tx.submissionByRequest(conversation.id, requestId), context);
+    const forget = (requestId) => harness.commit(async (tx) => {
+        delete (await tx.doc(Turns)).pending[requestId];
+    }, context);
+    async function withHistory(adapter, message) {
+        const text = message.text === "" && message.attachments.length === 0 ? BLANK_MESSAGE : message.text;
+        if (message.isDirect)
+            return { text, earlier: [] };
+        const after = await lastSeenCursor(harness, message);
+        const earlier = (await adapter.fetchThread(message, after).catch(() => [])).filter((other) => other.cursor < message.cursor && !other.isDirect && !other.mentionsBot);
+        await markThreadSeen(harness, message, message.cursor);
+        if (earlier.length === 0)
+            return { text, earlier };
+        const lines = earlier.map((other) => `${other.user.name ?? other.user.id}: ${other.text}${attachmentMarks(other)}`);
+        return {
+            text: `Messages in this thread since you last replied:\n${lines.join("\n")}\n\nThe message for you:\n${text}`,
+            earlier,
+        };
+    }
+    async function finish(adapter, conversation, requestId, ref, submission) {
+        finishing.set(conversation.id, (finishing.get(conversation.id) ?? 0) + 1);
+        try {
+            await settle(adapter, conversation, ref, submission);
+            await forget(requestId);
+        }
+        finally {
+            const left = (finishing.get(conversation.id) ?? 1) - 1;
+            if (left === 0) {
+                finishing.delete(conversation.id);
+                posted.delete(conversation.id);
+            }
+            else {
+                finishing.set(conversation.id, left);
+            }
+        }
+    }
+    async function settle(adapter, conversation, ref, submission) {
+        let finished = false;
+        let shown = "";
+        let lastUpdate = 0;
+        let updating = Promise.resolve();
+        const live = await harness.watchDoc(LiveDoc, conversation.id, context);
+        live?.start(async (value) => {
+            const text = liveStatusText(value).slice(-adapter.maxMessageLength);
+            if (finished || text === shown || Date.now() - lastUpdate < STATUS_INTERVAL_MS)
+                return;
+            shown = text;
+            lastUpdate = Date.now();
+            updating = adapter.update(ref, text).catch(() => undefined);
+            await updating;
+        });
+        const settled = await submission.wait(context);
+        finished = true;
+        await live?.stop();
+        await updating;
+        let reply;
+        switch (settled.status) {
+            case "done": {
+                if (settled.type === "write")
+                    throw new Error("turns submit inputs, not writes");
+                const answers = posted.get(conversation.id) ?? new Set();
+                if (answers.has(settled.answer)) {
+                    await adapter.remove(ref).catch(() => undefined);
+                    return;
+                }
+                posted.set(conversation.id, answers.add(settled.answer));
+                reply = answerText(await conversation.commit((tx) => tx.entry(AssistantEntry, settled.answer), context));
+                break;
+            }
+            case "unanswered":
+                console.error(`[turn] unanswered ${settled.reason} ${JSON.stringify(settled.detail ?? null)}`);
+                reply = `Sorry, I could not answer that (${settled.reason}).`;
+                break;
+            default:
+                throw new Error(`unknown submission status ${JSON.stringify(settled)}`);
+        }
+        const [first = "", ...rest] = chunkText(reply === "" ? "(no answer)" : reply, adapter.maxMessageLength);
+        await adapter.update(ref, first);
+        for (const chunk of rest)
+            await adapter.post(ref, chunk);
+    }
+    /** The turn's submission, once its input is admitted; inputs of one thread are admitted in the order they came. */
+    async function admit(adapter, message, requestId) {
+        const conversation = await openThread(harness, message, agent);
+        if ((await admitted(conversation, requestId)) !== undefined)
+            return undefined;
+        const ref = await adapter.post(message, PLACEHOLDER);
+        await harness.commit(async (tx) => {
+            (await tx.doc(Turns)).pending[requestId] = { ref, conversationId: conversation.id };
+        }, context);
+        const { text, earlier } = await withHistory(adapter, message);
+        const signal = AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS);
+        const read = await readAttachments(adapter, message, earlier, images, signal);
+        const submission = await conversation.submit({
+            type: "input",
+            content: inputContent(text, read),
+            whenBusy: "steer",
+            requestId,
+            entry: { kind: ChatMessageEntry.kind, data: message.user },
+        }, context);
+        return { conversation, ref, submission };
+    }
+    async function run(adapter, message) {
+        const requestId = `${message.platform}:${message.messageId}`;
+        if (inFlight.has(requestId))
+            return;
+        inFlight.add(requestId);
+        try {
+            const thread = `${message.platform}:${message.spaceId}:${message.threadId}`;
+            const turn = (admitting.get(thread) ?? Promise.resolve()).then(() => admit(adapter, message, requestId));
+            const done = turn.then(() => undefined, () => undefined);
+            admitting.set(thread, done);
+            void done.then(() => {
+                if (admitting.get(thread) === done)
+                    admitting.delete(thread);
+            });
+            const admittedTurn = await turn;
+            if (admittedTurn !== undefined) {
+                await finish(adapter, admittedTurn.conversation, requestId, admittedTurn.ref, admittedTurn.submission);
+            }
+        }
+        finally {
+            inFlight.delete(requestId);
+        }
+    }
+    async function resumeOne(adapter, requestId, turn) {
+        const conversation = await harness.conversation(turn.conversationId, context);
+        const record = conversation === undefined ? undefined : await admitted(conversation, requestId);
+        const submission = record === undefined ? undefined : await harness.submission(record.id, context);
+        if (conversation === undefined || submission === undefined) {
+            await adapter.update(turn.ref, RESTARTED).catch(() => undefined);
+            await forget(requestId);
+            return;
+        }
+        await finish(adapter, conversation, requestId, turn.ref, submission);
+    }
+    async function resume(adapters) {
+        const pending = (await harness.snapshot(Turns, context))?.pending ?? {};
+        await Promise.all(Object.entries(pending).map(async ([requestId, turn]) => {
+            const adapter = adapters.get(turn.ref.platform);
+            if (adapter === undefined || inFlight.has(requestId))
+                return;
+            inFlight.add(requestId);
+            try {
+                await resumeOne(adapter, requestId, turn);
+            }
+            catch (error) {
+                if (!closing)
+                    console.error(`[turn] could not finish ${requestId}`, error);
+            }
+            finally {
+                inFlight.delete(requestId);
+            }
+        }));
+    }
+    function handlers(adapter) {
+        return {
+            onMessage: async (message) => {
+                if (!message.isDirect && !message.mentionsBot)
+                    return;
+                await run(adapter, message).catch((error) => {
+                    if (!closing)
+                        console.error("[turn] failed", error);
+                });
+            },
+            onApproval: async (decision) => {
+                const feedback = await resolveApproval(harness, decision);
+                if (!feedback.counted)
+                    console.log(`[approvals] ${decision.approvalId} ${decision.user.id}: ${feedback.text}`);
+                return feedback;
+            },
+        };
+    }
+    return { run, resume, handlers };
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@ithousecall/chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Self-hosted IT helpdesk chat agent for Slack, Microsoft Teams, and Google Chat",
+  "homepage": "https://chat.ithousecall.app",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IT-Housecall/it-housecall-chat-agent.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "check": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings --type-aware && oxfmt --check .",
+    "format": "oxfmt .",
+    "test": "vitest run",
+    "ci": "npm run check && npm run lint && npm test"
+  },
+  "dependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-durable": "1.4.0",
+    "@earendil-works/pi-mcp": "1.4.0",
+    "@googleapis/chat": "51.3.0",
+    "@googleapis/drive": "27.0.0",
+    "@hono/node-server": "2.1.5",
+    "@microsoft/teams.api": "2.1.1",
+    "@microsoft/teams.apps": "2.1.1",
+    "@microsoft/teams.cards": "2.1.1",
+    "@slack/bolt": "5.1.0",
+    "google-auth-library": "11.3.1",
+    "hono": "4.13.13",
+    "turndown": "7.2.4",
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@slack/types": "3.2.0",
+    "@types/node": "26.6.5",
+    "@types/turndown": "5.0.6",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0",
+    "oxlint-tsgolint": "7.0.2005",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}