@ithousecall/chat 0.0.0-stage → 0.2.1

package/dist/extensions/approvals.js

@@ -0,0 +1,144 @@
+import { defineDocFamily, } from "@earendil-works/pi-durable";
+import { decisionText, } from "../chat/adapter.js";
+import { context } from "../harness.js";
+import { requester, ThreadDoc } from "../threads.js";
+const Approvals = defineDocFamily({
+    kind: "app.approvals",
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: (seed) => ({ ...seed, status: "pending", decidedBy: null }),
+    checkpointWhen: () => true,
+});
+let transport;
+/** Write tools ask for approval through these adapters; set once at startup. */
+export function setApprovalTransport(next) {
+    transport = next;
+}
+function failure(text) {
+    return { output: [{ type: "text", text }], isError: true };
+}
+const MAX_TIMER_MS = 2 ** 31 - 1;
+async function awaitDecision(api, seed, deadline, ctx) {
+    const approvalId = seed.prompt.approvalId;
+    const watch = await api.watchDoc(Approvals, approvalId, ctx);
+    if (watch === undefined)
+        throw new Error(`approval ${approvalId} is missing`);
+    const expire = () => api
+        .commit(async (tx) => {
+        const approval = await tx.doc(Approvals, approvalId, seed);
+        if (approval.status === "pending")
+            approval.status = "expired";
+    }, ctx)
+        .catch(() => undefined);
+    const timer = setTimeout(() => void expire(), Math.min(MAX_TIMER_MS, Math.max(0, deadline - api.now())));
+    try {
+        return await new Promise((resolve, reject) => {
+            const check = (value) => {
+                if (value !== null && value.status !== "pending")
+                    resolve(value.status);
+            };
+            check(watch.value);
+            watch.start(async (value) => check(value));
+            void watch.closed.then((end) => reject(new Error(`approval watch ended: ${end.reason}`)));
+            ctx.abortSignal?.addEventListener("abort", () => reject(new Error("approval wait aborted")), { once: true });
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        await watch.stop();
+    }
+}
+/**
+ * A tool that runs only after its requester, the author of the message that led to the call, confirms it in chat.
+ * Replay-safe: after a restart the call reruns, finds its approval and posted prompt, and keeps waiting.
+ */
+export function withApproval(tool, summarize) {
+    return {
+        ...tool,
+        replay: "safe",
+        execute: async (args, api, ctx) => {
+            const gate = transport;
+            if (gate === undefined)
+                return failure("Approvals are not set up, so this action cannot run.");
+            const thread = await api.snapshot(ThreadDoc, api.conversationId, ctx);
+            const adapter = thread === undefined ? undefined : gate.adapters.get(thread.platform);
+            const asker = await requester(api, ctx);
+            if (thread === undefined || adapter === undefined || asker === undefined) {
+                return failure("This action needs a chat thread to ask for approval in.");
+            }
+            const approvalId = String(api.taskId);
+            await api.commit(async (tx) => {
+                await tx.doc(Approvals, approvalId, {
+                    prompt: {
+                        approvalId,
+                        tool: tool.name,
+                        summary: summarize(args),
+                        args: structuredClone(args),
+                        requester: structuredClone(asker),
+                    },
+                    conversationId: api.conversationId,
+                    createdAt: api.now(),
+                });
+            }, ctx);
+            const stored = await api.snapshot(Approvals, approvalId, ctx);
+            if (stored === undefined)
+                throw new Error(`approval ${approvalId} is missing`);
+            const { prompt } = stored;
+            const ref = (await api.memo("prompt", ctx)) ??
+                (await api.memo("prompt", await adapter.postApproval(thread, prompt), ctx));
+            const outcome = await awaitDecision(api, stored, stored.createdAt + gate.timeoutMs, ctx);
+            const decidedBy = (await api.snapshot(Approvals, prompt.approvalId, ctx))?.decidedBy ?? undefined;
+            await adapter
+                .resolveApprovalMessage(ref, prompt, outcome, decidedBy)
+                .catch((error) => console.error("could not update the approval message", error));
+            switch (outcome) {
+                case "approved":
+                    break;
+                case "denied":
+                    return failure("The user denied this action. Do not retry it unless they ask for it again.");
+                case "expired":
+                    return failure("Nobody approved this action in time. Ask the user whether to try again.");
+                default:
+                    throw new Error(`unknown approval outcome ${JSON.stringify(outcome)}`);
+            }
+            if ((await api.memo("started", ctx)) === true) {
+                return failure("This action was interrupted after it started and may already have taken effect. Check before retrying.");
+            }
+            await api.memo("started", true, ctx);
+            return tool.execute(args, api, ctx);
+        },
+    };
+}
+/** Records the requester's decision; anyone else's click, or a late one, changes nothing. */
+export async function resolveApproval(harness, decision) {
+    const current = await harness.snapshot(Approvals, decision.approvalId, context);
+    if (current === undefined)
+        return { counted: false, text: "This approval request no longer exists." };
+    const seed = structuredClone({
+        prompt: current.prompt,
+        conversationId: current.conversationId,
+        createdAt: current.createdAt,
+    });
+    return harness.commit(async (tx) => {
+        const approval = await tx.doc(Approvals, decision.approvalId, seed);
+        const { requester: asker } = approval.prompt;
+        if (approval.status !== "pending")
+            return { counted: false, text: `This request was already ${approval.status}.` };
+        if (asker.id !== decision.user.id) {
+            return { counted: false, text: `Only ${asker.name ?? asker.id} can approve or deny this request.` };
+        }
+        switch (decision.decision) {
+            case "approve":
+                approval.status = "approved";
+                break;
+            case "deny":
+                approval.status = "denied";
+                break;
+            default:
+                throw new Error(`unknown decision ${JSON.stringify(decision.decision)}`);
+        }
+        approval.decidedBy = structuredClone(decision.user);
+        return { counted: true, text: decisionText(seed.prompt, approval.status, decision.user) };
+    }, context);
+}

package/dist/extensions/mcp.d.ts

@@ -0,0 +1,10 @@
+import { type Registry } from "@earendil-works/pi-durable";
+import { type McpTransport } from "@earendil-works/pi-mcp";
+import type { McpServerConfig } from "../config.ts";
+/** Providers accept tool names of at most 64 characters from [A-Za-z0-9_-]. */
+export declare function mcpToolName(server: string, tool: string): string;
+/**
+ * Connect each server in the background and install its tools as extension `mcp:<name>`. A dropped connection
+ * reconnects with backoff; meanwhile its tools answer with an error.
+ */
+export declare function startMcp(registry: Registry, servers: readonly McpServerConfig[], connect?: (server: McpServerConfig) => McpTransport): () => Promise<void>;

package/dist/extensions/mcp.js

@@ -0,0 +1,127 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension } from "@earendil-works/pi-durable";
+import { McpClient, StdioTransport, StreamableHttpTransport, toLlmContent, } from "@earendil-works/pi-mcp";
+import { defineTool } from "./tool.js";
+/** Providers accept tool names of at most 64 characters from [A-Za-z0-9_-]. */
+export function mcpToolName(server, tool) {
+    return `mcp__${server}__${tool}`.replaceAll(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+}
+/** Tools whose housecall name another tool of the server already took are skipped. */
+function uniquelyNamed(server, tools) {
+    const seen = new Map();
+    return tools.filter((tool) => {
+        const name = mcpToolName(server, tool.name);
+        const taken = seen.get(name);
+        if (taken === undefined) {
+            seen.set(name, tool.name);
+            return true;
+        }
+        console.error(`[mcp] ${server}: skipping tool "${tool.name}", its name ${name} is taken by "${taken}"`);
+        return false;
+    });
+}
+/**
+ * The server's tools as housecall tools. Only the tools listed in `read_only` run without approval; the server's own
+ * `readOnlyHint` is not trusted.
+ */
+function mcpExtension(server, tools, readOnly, client) {
+    return defineExtension({
+        name: `mcp:${server}`,
+        tools: uniquelyNamed(server, tools).map((tool) => {
+            const parameters = Type.Unsafe({
+                ...tool.inputSchema,
+                type: "object",
+                properties: tool.inputSchema.properties ?? {},
+            });
+            const write = !readOnly.includes(tool.name);
+            return defineTool({
+                name: mcpToolName(server, tool.name),
+                description: tool.description ?? tool.title ?? tool.name,
+                parameters,
+                ...(write
+                    ? { write: true, summary: () => `${server}: ${tool.annotations?.title ?? tool.title ?? tool.name}` }
+                    : {}),
+                execute: async (args, _api, context) => {
+                    const connected = client();
+                    if (connected?.connectionState !== "connected") {
+                        return {
+                            output: [{ type: "text", text: `The ${server} server is not connected right now. Try again later.` }],
+                            isError: true,
+                        };
+                    }
+                    const result = await connected.callTool(tool.name, args, context.abortSignal === undefined ? {} : { signal: context.abortSignal });
+                    return { output: toLlmContent(result), isError: result.isError === true };
+                },
+            });
+        }),
+    });
+}
+// MCP servers get only these variables and their configured env, never housecall's own secrets.
+const INHERITED_ENV = ["PATH", "HOME", "USER", "LANG", "TMPDIR"];
+function transport(server) {
+    if ("url" in server)
+        return new StreamableHttpTransport({ url: server.url, headers: server.headers });
+    const base = Object.fromEntries(INHERITED_ENV.flatMap((name) => (process.env[name] === undefined ? [] : [[name, process.env[name]]])));
+    return new StdioTransport({
+        command: server.command,
+        args: server.args,
+        env: { ...base, ...server.env },
+        inheritEnv: false,
+        stderr: "pipe",
+        onStderr: (chunk) => process.stderr.write(`[mcp:${server.name}] ${chunk}`),
+    });
+}
+const MAX_BACKOFF_MS = 60_000;
+/**
+ * Connect each server in the background and install its tools as extension `mcp:<name>`. A dropped connection
+ * reconnects with backoff; meanwhile its tools answer with an error.
+ */
+export function startMcp(registry, servers, connect = transport) {
+    const stopping = new AbortController();
+    const clients = new Map();
+    /** One connection, until it drops; true if it got as far as listing tools. */
+    async function session(server) {
+        const client = new McpClient({ name: "housecall", version: "0.1.0" });
+        const close = () => void client.close().catch(() => undefined);
+        stopping.signal.addEventListener("abort", close, { once: true });
+        try {
+            const closed = new Promise((resolve) => client.onClose(resolve));
+            await client.connect(connect(server));
+            clients.set(server.name, client);
+            const install = async () => registry.install(mcpExtension(server.name, await client.listTools(), server.read_only, () => clients.get(server.name)));
+            await install();
+            client.onNotification("notifications/tools/list_changed", () => void install().catch(() => undefined));
+            console.log(`[mcp] ${server.name}: connected`);
+            await closed;
+            return true;
+        }
+        catch (error) {
+            if (!stopping.signal.aborted) {
+                console.error(`[mcp] ${server.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return false;
+        }
+        finally {
+            stopping.signal.removeEventListener("abort", close);
+            close();
+        }
+    }
+    async function serve(server) {
+        let backoff = 1000;
+        for (;;) {
+            if (await session(server))
+                backoff = 1000;
+            if (stopping.signal.aborted)
+                return;
+            console.error(`[mcp] ${server.name}: disconnected, retrying in ${backoff / 1000}s`);
+            await sleep(backoff, undefined, { signal: stopping.signal }).catch(() => undefined);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+    const running = servers.map(serve);
+    return async () => {
+        stopping.abort();
+        await Promise.all(running);
+    };
+}

package/dist/extensions/tool.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from "@earendil-works/chord";
+import type { Static, TSchema } from "@earendil-works/pi-ai";
+import { type ToolExecutionApi, type ToolExecutionResult, type ToolRegistration } from "@earendil-works/pi-durable";
+export type AgentTool<P extends TSchema> = Omit<ToolRegistration<P>, "replay" | "execute"> & {
+    /**
+     * The tool changes something outside @housecall: the requester must approve each call in chat before `execute` runs.
+     * Tools without it must be safe to run again after a restart.
+     */
+    write?: true;
+    /** One line for the approval prompt; default: the tool name. */
+    summary?: (args: Static<P>) => string;
+    execute(args: Static<P>, api: ToolExecutionApi, context: Context): Promise<ToolExecutionResult>;
+};
+export declare function defineTool<P extends TSchema>(tool: AgentTool<P>): ToolRegistration<P>;

package/dist/extensions/tool.js

@@ -0,0 +1,8 @@
+import { defineTool as defineDurableTool, } from "@earendil-works/pi-durable";
+import { withApproval } from "./approvals.js";
+export function defineTool(tool) {
+    const { write, summary, ...registration } = tool;
+    if (write === undefined)
+        return defineDurableTool({ ...registration, replay: "safe" });
+    return withApproval(defineDurableTool(registration), summary ?? (() => tool.name));
+}

package/dist/format.d.ts

@@ -0,0 +1,7 @@
+import type { EntryRecord, LiveState } from "@earendil-works/pi-durable";
+export declare const PLACEHOLDER = "Looking into it\u2026";
+export declare function escapeHtml(text: string): string;
+export declare function answerText(entry: EntryRecord | undefined): string;
+export declare function liveStatusText(live: Readonly<LiveState> | null): string;
+/** Split text into pieces of at most `max` characters, preferring paragraph, then line, then word boundaries. */
+export declare function chunkText(text: string, max: number): string[];

package/dist/format.js

@@ -0,0 +1,36 @@
+export const PLACEHOLDER = "Looking into it…";
+export function escapeHtml(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export function answerText(entry) {
+    return (entry?.model ?? [])
+        .flatMap((message) => (message.role === "assistant" ? message.content : []))
+        .flatMap((block) => (block.type === "text" ? [block.text] : []))
+        .join("")
+        .trim();
+}
+export function liveStatusText(live) {
+    const partial = (live?.generation?.message?.content ?? [])
+        .flatMap((block) => (block.type === "text" ? [block.text] : []))
+        .join("")
+        .trim();
+    if (partial !== "")
+        return partial;
+    const tools = (live?.tools ?? []).map((tool) => `${tool.status === "done" ? "✓" : "…"} \`${tool.name}\``);
+    return [PLACEHOLDER, ...tools].join("\n");
+}
+/** Split text into pieces of at most `max` characters, preferring paragraph, then line, then word boundaries. */
+export function chunkText(text, max) {
+    const chunks = [];
+    let rest = text;
+    while (rest.length > max) {
+        const window = rest.slice(0, max);
+        const cut = [window.lastIndexOf("\n\n"), window.lastIndexOf("\n"), window.lastIndexOf(" ")].find((index) => index > max / 2);
+        const at = cut === undefined ? max : cut + 1;
+        chunks.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at).trimStart();
+    }
+    if (rest !== "" || chunks.length === 0)
+        chunks.push(rest);
+    return chunks;
+}

package/dist/harness.d.ts

@@ -0,0 +1,4 @@
+import type { Models } from "@earendil-works/pi-ai";
+import { Harness, type Registry } from "@earendil-works/pi-durable";
+export declare const context: import("@earendil-works/chord/context").Context;
+export declare function openHarness(path: string, models: Models, registry: Registry): Promise<Harness>;

package/dist/harness.js

@@ -0,0 +1,14 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { Harness } from "@earendil-works/pi-durable";
+import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";
+export const context = BACKGROUND_CONTEXT;
+export async function openHarness(path, models, registry) {
+    const storage = await openNodeSqliteStorage(path);
+    return Harness.open(storage, {
+        models,
+        registry,
+        identity: { attribution: { name: "housecall", url: "https://github.com/IT-Housecall/it-housecall-chat-agent" } },
+        settings: { afterFailedRun: "continue" },
+        onReport: (error, info) => console.error(`[harness] ${info.type}`, error),
+    }, context);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Type } from "@earendil-works/pi-ai";
+export { defineExtension } from "@earendil-works/pi-durable";
+export type { Extension, ToolExecutionApi, ToolExecutionResult } from "@earendil-works/pi-durable";
+export type { ChatUser } from "./chat/adapter.ts";
+export { defineTool, type AgentTool } from "./extensions/tool.ts";
+export { start, type StartOptions } from "./start.ts";
+export { requester } from "./threads.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Type } from "@earendil-works/pi-ai";
+export { defineExtension } from "@earendil-works/pi-durable";
+export { defineTool } from "./extensions/tool.js";
+export { start } from "./start.js";
+export { requester } from "./threads.js";

package/dist/lock.d.ts

@@ -0,0 +1,2 @@
+/** pi-durable storage has no cross-process locking, so one housecall process owns `dir` at a time. */
+export declare function acquireLock(dir: string): () => void;

package/dist/lock.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { ConfigError } from "./config.js";
+/** pi-durable storage has no cross-process locking, so one housecall process owns `dir` at a time. */
+export function acquireLock(dir) {
+    const db = new DatabaseSync(join(dir, "housecall.lock"), { timeout: 0 });
+    try {
+        db.exec("PRAGMA locking_mode = EXCLUSIVE; BEGIN EXCLUSIVE; COMMIT;");
+    }
+    catch (error) {
+        db.close();
+        if (error instanceof Error && error.message.includes("database is locked")) {
+            throw new ConfigError(`another @housecall is already using ${dir}/`);
+        }
+        throw error;
+    }
+    return () => db.close();
+}

package/dist/model.d.ts

@@ -0,0 +1,14 @@
+import type { Models } from "@earendil-works/pi-ai";
+import type { ModelRef } from "@earendil-works/pi-durable";
+import type { ImageLimits } from "@earendil-works/pi-durable/tools";
+import { type ModelConfig } from "./config.ts";
+/** `imageLimits` is set when the model takes image input. */
+type ModelSetup = {
+    models: Models;
+    model: ModelRef;
+    imageLimits?: ImageLimits;
+};
+/** The environment variable that holds the model's API key. */
+export declare function modelKeyEnv(config: ModelConfig): string;
+export declare function createModelSetup(config: ModelConfig): ModelSetup;
+export {};

package/dist/model.js

@@ -0,0 +1,87 @@
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { createModels, createProvider } from "@earendil-works/pi-ai/models";
+import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { ConfigError } from "./config.js";
+const PROVIDER_ID = "llm";
+/** Anthropic scales a longer edge down to 1568 pixels anyway. */
+const CHAT_IMAGE_LIMITS = { maxWidth: 1568, maxHeight: 1568, maxBytes: 1024 * 1024 };
+/** The environment variable that holds the model's API key. */
+export function modelKeyEnv(config) {
+    switch (config.provider) {
+        case "openai_compatible":
+            return config.api_key_env;
+        case "openai":
+            return "OPENAI_API_KEY";
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        default:
+            throw new ConfigError(`model.provider: unknown provider ${JSON.stringify(config)}`);
+    }
+}
+export function createModelSetup(config) {
+    const models = createModels();
+    switch (config.provider) {
+        case "openai_compatible": {
+            const keyEnv = config.api_key_env;
+            models.setProvider(createProvider({
+                id: PROVIDER_ID,
+                name: "OpenAI-compatible endpoint",
+                baseUrl: config.base_url,
+                auth: {
+                    apiKey: {
+                        name: keyEnv,
+                        resolve: () => {
+                            const apiKey = process.env[keyEnv];
+                            return Promise.resolve(apiKey === undefined || apiKey === "" ? undefined : { auth: { apiKey }, source: keyEnv });
+                        },
+                    },
+                },
+                api: openAICompletionsApi(),
+                models: [
+                    {
+                        id: config.id,
+                        name: config.id,
+                        api: "openai-completions",
+                        provider: PROVIDER_ID,
+                        baseUrl: config.base_url,
+                        input: config.images ? ["text", "image"] : ["text"],
+                        reasoning: config.reasoning,
+                        contextWindow: config.context_window,
+                        maxTokens: config.max_tokens,
+                        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                        compat: { supportsDeveloperRole: false },
+                    },
+                ],
+            }));
+            return withImageLimits(models, { provider: PROVIDER_ID, modelId: config.id });
+        }
+        case "openai":
+            models.setProvider(openaiProvider());
+            break;
+        case "anthropic":
+            models.setProvider(anthropicProvider());
+            break;
+        default:
+            throw new ConfigError(`model.provider: unknown provider ${JSON.stringify(config)}`);
+    }
+    if (models.getModel(config.provider, config.id) === undefined) {
+        throw new ConfigError(`model.id: ${config.provider} has no model "${config.id}"`);
+    }
+    return withImageLimits(models, { provider: config.provider, modelId: config.id });
+}
+function withImageLimits(models, model) {
+    const found = models.getModel(model.provider, model.modelId);
+    if (found?.input.includes("image") !== true)
+        return { models, model };
+    const resize = found.inputLimits?.images?.resize;
+    return {
+        models,
+        model,
+        imageLimits: {
+            maxWidth: Math.min(resize?.maxWidth ?? Infinity, CHAT_IMAGE_LIMITS.maxWidth),
+            maxHeight: Math.min(resize?.maxHeight ?? Infinity, CHAT_IMAGE_LIMITS.maxHeight),
+            maxBytes: Math.min(resize?.maxBytes ?? Infinity, CHAT_IMAGE_LIMITS.maxBytes),
+        },
+    };
+}

package/dist/prompt.d.ts

@@ -0,0 +1,2 @@
+import { type Extension } from "@earendil-works/pi-durable";
+export declare const PromptExtension: Extension;

package/dist/prompt.js

@@ -0,0 +1,15 @@
+import { defineExtension, GenerationTask, hook, section } from "@earendil-works/pi-durable";
+import { olderImagesHidden } from "./attachments.js";
+const PROMPT = `You are @housecall, the IT helpdesk assistant in your company's chat.
+People message you when something on their computer or account is not working, or when they need to know how to do something.
+
+- Keep answers short and concrete: numbered steps the person can follow, in plain language.
+- Write Markdown: **bold**, lists, \`code\`, and [title](url) links. No tables or HTML.
+- Never invent internal procedures, links, or settings. If you do not know, say so and suggest who to contact.
+- Some actions need the person's approval; the chat asks them for you. Do not ask them to confirm a tool call yourself.
+- Each thread is one conversation. Earlier messages in the thread may be included for context.`;
+export const PromptExtension = defineExtension({
+    name: "prompt",
+    sections: [section("housecall", () => PROMPT, { tag: false })],
+    hooks: [hook(GenerationTask, { beforeRequest: ({ messages }) => ({ messages: olderImagesHidden(messages) }) })],
+});

package/dist/start.d.ts

@@ -0,0 +1,13 @@
+import { type Extension } from "@earendil-works/pi-durable";
+export type StartOptions = {
+    /** The config file, relative to the working directory. */
+    config: string;
+    /** The state directory, relative to the working directory. One process may use it at a time. */
+    data: string;
+    extensions?: Extension[];
+};
+/**
+ * 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 declare function start(options: StartOptions): Promise<void>;