@lapis-notes/ai 0.1.0

package/dist/tools/app-tool-host.js

@@ -0,0 +1,419 @@
+import { createAppToolExecutionScope, } from "@lapis-notes/api/agent-tools";
+import Ajv, {} from "ajv";
+import { isAppToolEnabled, } from "../settings/ai-settings";
+const MAX_CONTENT_ITEMS = 32;
+const MAX_TEXT_BYTES = 64 * 1024;
+const MAX_STRUCTURED_BYTES = 64 * 1024;
+const MAX_IMAGE_DATA_BYTES = 5 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 60_000;
+export class AppToolExecutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AppToolExecutionError";
+    }
+}
+export class AppToolApprovalBroker {
+    #listeners = new Set();
+    #pending = new Map();
+    #sequence = 0;
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    request(bindingId, tool, input, details, signal) {
+        if (signal.aborted) {
+            return Promise.reject(cancelledError());
+        }
+        const id = `app-tool-approval-${++this.#sequence}`;
+        const request = {
+            id,
+            origin: "app-tool",
+            kind: tool.tool.effect === "external" ? "network" : "write",
+            title: details?.title ?? `Allow ${tool.tool.name}`,
+            tool: { name: tool.tool.name, input },
+            options: [
+                { id: "allow-once", label: "Allow once", kind: "allow-once" },
+                {
+                    id: "allow-session",
+                    label: "Allow for this session",
+                    kind: "allow-session",
+                },
+                { id: "deny-once", label: "Deny", kind: "deny-once" },
+            ],
+            details: {
+                description: details?.description,
+                path: details?.path ?? details?.paths?.join(", "),
+                diff: formatApprovalDiff(details),
+            },
+        };
+        const decision = new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const pending = this.#pending.get(id);
+                if (!pending)
+                    return;
+                this.#pending.delete(id);
+                pending.removeAbortListener();
+                reject(cancelledError());
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.#pending.set(id, {
+                bindingId,
+                resolve,
+                reject,
+                removeAbortListener: () => signal.removeEventListener("abort", onAbort),
+            });
+        });
+        for (const listener of this.#listeners)
+            listener(request, bindingId);
+        return decision;
+    }
+    respond(requestId, decision) {
+        const pending = this.#pending.get(requestId);
+        if (!pending)
+            return false;
+        if (!isAppToolApprovalDecision(decision))
+            return false;
+        this.#pending.delete(requestId);
+        pending.removeAbortListener();
+        pending.resolve(decision);
+        return true;
+    }
+    closeBinding(bindingId) {
+        for (const [requestId, pending] of this.#pending) {
+            if (pending.bindingId !== bindingId)
+                continue;
+            this.#pending.delete(requestId);
+            pending.removeAbortListener();
+            pending.reject(cancelledError());
+        }
+    }
+    close() {
+        for (const pending of this.#pending.values()) {
+            pending.removeAbortListener();
+            pending.reject(cancelledError());
+        }
+        this.#pending.clear();
+        this.#listeners.clear();
+    }
+}
+export class AppToolHost {
+    registry;
+    settings;
+    timeoutMs;
+    approvals = new AppToolApprovalBroker();
+    #ajv = new Ajv({ allErrors: true, strict: false });
+    #sessions = new Map();
+    #grants = new Set();
+    #validators = new Map();
+    #activeInvocations = new Map();
+    #registryChangeRef;
+    constructor(registry, settings, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.registry = registry;
+        this.settings = settings;
+        this.timeoutMs = timeoutMs;
+        this.#registryChangeRef = registry.on("changed", (change) => {
+            if (change.reason !== "unregistered")
+                return;
+            this.expireOwner(change.ownerPluginId);
+            this.#validators.delete(change.registrationId);
+        });
+    }
+    createSession(input) {
+        if (this.#sessions.has(input.agentBindingId)) {
+            throw new Error(`App tool binding already exists: ${input.agentBindingId}`);
+        }
+        const scope = createAppToolExecutionScope(input.scopeDir);
+        const settings = this.settings();
+        const eligible = settings.appToolsEnabled && input.runtimeSupportsAppTools
+            ? this.registry
+                .list()
+                .filter((registered) => isEligible(registered, settings))
+                .map(toDescriptor)
+            : [];
+        const descriptor = Object.freeze({
+            conversationId: input.conversationId,
+            agentBindingId: input.agentBindingId,
+            scopeDir: scope.directory,
+            launchNotePath: input.launchNotePath,
+            tools: Object.freeze(eligible),
+        });
+        this.#sessions.set(input.agentBindingId, { descriptor, scope });
+        return descriptor;
+    }
+    getSession(agentBindingId) {
+        return this.#sessions.get(agentBindingId)?.descriptor;
+    }
+    async invoke(agentBindingId, call, signal) {
+        const session = this.#sessions.get(agentBindingId);
+        if (!session)
+            throw unavailableError(call.name);
+        const snapshot = session.descriptor.tools.find((descriptor) => descriptor.name === call.name);
+        if (!snapshot)
+            throw unavailableError(call.name);
+        const registered = this.registry.resolve(snapshot.name, snapshot.registrationId);
+        if (!registered)
+            throw unavailableError(call.name);
+        const invocation = createInvocationSignal(signal, this.timeoutMs);
+        const activeForBinding = this.#activeInvocations.get(agentBindingId) ?? new Set();
+        activeForBinding.add(invocation.cancel);
+        this.#activeInvocations.set(agentBindingId, activeForBinding);
+        const context = Object.freeze({
+            conversationId: session.descriptor.conversationId,
+            agentBindingId: session.descriptor.agentBindingId,
+            runId: call.runId,
+            toolCallId: call.toolCallId,
+            scope: session.scope,
+            launchNotePath: session.descriptor.launchNotePath,
+            signal: invocation.signal,
+        });
+        try {
+            this.validateInput(registered, call.input);
+            let grantForSession = false;
+            if (registered.tool.effect !== "read" &&
+                !this.#grants.has(grantKey(session.descriptor, registered))) {
+                const details = registered.tool.describeApproval
+                    ? await raceWithAbort(registered.tool.describeApproval(call.input, context), invocation.signal)
+                    : undefined;
+                const decision = await this.approvals.request(agentBindingId, registered, call.input, details, invocation.signal);
+                if (decision === "deny-once") {
+                    throw new AppToolExecutionError("approval_denied", `Permission denied for app tool: ${call.name}`);
+                }
+                if (decision === "allow-session") {
+                    grantForSession = true;
+                }
+            }
+            if (!this.registry.resolve(snapshot.name, snapshot.registrationId)) {
+                throw unavailableError(call.name);
+            }
+            if (grantForSession) {
+                this.#grants.add(grantKey(session.descriptor, registered));
+            }
+            const result = await raceWithAbort(registered.tool.execute(call.input, context), invocation.signal);
+            this.validateResult(registered, result);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof AppToolExecutionError) {
+                if (error.code === "cancelled" && invocation.timedOut()) {
+                    throw new AppToolExecutionError("timed_out", `App tool timed out: ${call.name}`);
+                }
+                throw error;
+            }
+            if (invocation.signal.aborted) {
+                throw new AppToolExecutionError(invocation.timedOut() ? "timed_out" : "cancelled", invocation.timedOut()
+                    ? `App tool timed out: ${call.name}`
+                    : `App tool cancelled: ${call.name}`);
+            }
+            throw new AppToolExecutionError("execution_failed", `App tool execution failed: ${call.name}`);
+        }
+        finally {
+            activeForBinding.delete(invocation.cancel);
+            if (activeForBinding.size === 0) {
+                this.#activeInvocations.delete(agentBindingId);
+            }
+            invocation.dispose();
+        }
+    }
+    closeBinding(agentBindingId) {
+        this.#sessions.delete(agentBindingId);
+        for (const cancel of this.#activeInvocations.get(agentBindingId) ?? []) {
+            cancel();
+        }
+        this.#activeInvocations.delete(agentBindingId);
+        this.approvals.closeBinding(agentBindingId);
+        for (const key of this.#grants) {
+            if (key.includes(`\u0000${agentBindingId}\u0000`))
+                this.#grants.delete(key);
+        }
+    }
+    expireOwner(ownerPluginId) {
+        for (const key of this.#grants) {
+            if (key.includes(`\u0000${ownerPluginId}\u0000`))
+                this.#grants.delete(key);
+        }
+    }
+    close() {
+        for (const bindingId of this.#sessions.keys())
+            this.closeBinding(bindingId);
+        this.approvals.close();
+        this.registry.offref(this.#registryChangeRef);
+        this.#validators.clear();
+    }
+    validateInput(registered, input) {
+        let validate = this.#validators.get(registered.registrationId);
+        if (!validate) {
+            try {
+                validate = this.#ajv.compile(registered.tool.inputSchema);
+            }
+            catch {
+                throw new AppToolExecutionError("invalid_tool_schema", `App tool has an invalid input schema: ${registered.tool.name}`);
+            }
+            this.#validators.set(registered.registrationId, validate);
+        }
+        if (!validate(input)) {
+            throw new AppToolExecutionError("invalid_arguments", `Invalid arguments for app tool: ${registered.tool.name}`);
+        }
+    }
+    validateResult(registered, result) {
+        if (!result || !Array.isArray(result.content)) {
+            throw invalidResult(registered.tool.name);
+        }
+        if (result.content.length > MAX_CONTENT_ITEMS) {
+            throw invalidResult(registered.tool.name);
+        }
+        let textBytes = 0;
+        for (const item of result.content) {
+            if (item.type === "text") {
+                if (typeof item.text !== "string")
+                    throw invalidResult(registered.tool.name);
+                textBytes += byteLength(item.text);
+            }
+            else if (item.type === "image") {
+                if (typeof item.data !== "string" ||
+                    typeof item.mimeType !== "string" ||
+                    !item.mimeType.startsWith("image/") ||
+                    byteLength(item.data) > MAX_IMAGE_DATA_BYTES) {
+                    throw invalidResult(registered.tool.name);
+                }
+            }
+            else {
+                throw invalidResult(registered.tool.name);
+            }
+        }
+        if (textBytes > MAX_TEXT_BYTES)
+            throw invalidResult(registered.tool.name);
+        if (result.structuredContent !== undefined) {
+            let encoded;
+            try {
+                encoded = JSON.stringify(result.structuredContent);
+            }
+            catch {
+                throw invalidResult(registered.tool.name);
+            }
+            if (byteLength(encoded) > MAX_STRUCTURED_BYTES) {
+                throw invalidResult(registered.tool.name);
+            }
+            if (registered.tool.outputSchema) {
+                let validate;
+                try {
+                    validate = this.#ajv.compile(registered.tool.outputSchema);
+                }
+                catch {
+                    throw new AppToolExecutionError("invalid_tool_schema", `App tool has an invalid output schema: ${registered.tool.name}`);
+                }
+                if (!validate(result.structuredContent)) {
+                    throw invalidResult(registered.tool.name);
+                }
+            }
+        }
+    }
+}
+function isEligible(registered, settings) {
+    return isAppToolEnabled({ name: registered.tool.name, owner: registered.owner }, settings);
+}
+function toDescriptor(registered) {
+    return Object.freeze({
+        registrationId: registered.registrationId,
+        ownerPluginId: registered.owner.pluginId,
+        name: registered.tool.name,
+        description: registered.tool.description,
+        inputSchema: cloneJson(registered.tool.inputSchema),
+        outputSchema: registered.tool.outputSchema
+            ? cloneJson(registered.tool.outputSchema)
+            : undefined,
+        effect: registered.tool.effect,
+    });
+}
+function cloneJson(value) {
+    return deepFreezeJson(JSON.parse(JSON.stringify(value)));
+}
+function deepFreezeJson(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    for (const nested of Object.values(value))
+        deepFreezeJson(nested);
+    return Object.freeze(value);
+}
+function grantKey(session, registered) {
+    return [
+        "",
+        session.conversationId,
+        session.agentBindingId,
+        session.scopeDir,
+        registered.owner.pluginId,
+        registered.tool.name,
+        registered.tool.effect,
+        "",
+    ].join("\u0000");
+}
+function unavailableError(name) {
+    return new AppToolExecutionError("tool_unavailable", `App tool is unavailable for this binding: ${name}`);
+}
+function invalidResult(name) {
+    return new AppToolExecutionError("invalid_result", `App tool returned an invalid or oversized result: ${name}`);
+}
+function cancelledError() {
+    return new AppToolExecutionError("cancelled", "App tool call cancelled.");
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function formatApprovalDiff(details) {
+    if (!details)
+        return undefined;
+    const hunks = [
+        ...(details.diff
+            ? [{ path: details.path, before: details.diff.before, after: details.diff.after }]
+            : []),
+        ...(details.diffs ?? []),
+    ];
+    if (hunks.length === 0)
+        return undefined;
+    return hunks
+        .map((hunk) => {
+        const header = hunk.path ? `# ${hunk.path}\n` : "";
+        return `${header}--- before\n${hunk.before}\n+++ after\n${hunk.after}`;
+    })
+        .join("\n\n");
+}
+function isAppToolApprovalDecision(decision) {
+    return ["allow-once", "allow-session", "deny-once"].includes(decision);
+}
+function createInvocationSignal(parent, timeoutMs) {
+    const controller = new AbortController();
+    let timeoutReached = false;
+    const onParentAbort = () => controller.abort(parent?.reason);
+    parent?.addEventListener("abort", onParentAbort, { once: true });
+    if (parent?.aborted)
+        controller.abort(parent.reason);
+    const timer = setTimeout(() => {
+        timeoutReached = true;
+        controller.abort();
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        timedOut: () => timeoutReached,
+        cancel: () => controller.abort(),
+        dispose: () => {
+            clearTimeout(timer);
+            parent?.removeEventListener("abort", onParentAbort);
+        },
+    };
+}
+function raceWithAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(cancelledError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(cancelledError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}

package/dist/tools/desktop-app-tool-bridge.d.ts

@@ -0,0 +1,23 @@
+import type { AgentEvent, AppToolSessionDescriptor, ApprovalOptionKind } from "../core/types";
+import { AppToolHost, type CreateAppToolSessionInput } from "./app-tool-host";
+export type AppToolBridgeEvent = {
+    bindingId: string;
+    event: AgentEvent;
+};
+export interface AppToolBridgeCoordinator {
+    prepare(input: CreateAppToolSessionInput): Promise<AppToolSessionDescriptor>;
+    closeBinding(bindingId: string): Promise<void>;
+    respondToApproval(requestId: string, decision: ApprovalOptionKind): boolean;
+    subscribe(listener: (event: AppToolBridgeEvent) => void): () => void;
+    close(): Promise<void>;
+}
+export declare class DesktopAppToolBridge implements AppToolBridgeCoordinator {
+    #private;
+    private readonly host;
+    constructor(host: AppToolHost);
+    prepare(input: CreateAppToolSessionInput): Promise<AppToolSessionDescriptor>;
+    respondToApproval(requestId: string, decision: ApprovalOptionKind): boolean;
+    subscribe(listener: (event: AppToolBridgeEvent) => void): () => void;
+    closeBinding(bindingId: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/tools/desktop-app-tool-bridge.js

@@ -0,0 +1,223 @@
+import { getNativeDesktopBridge, getNativeDesktopCapability, } from "@lapis-notes/api/desktop-native";
+import { AppToolExecutionError, AppToolHost, } from "./app-tool-host";
+const APP_TOOL_MCP_SERVER_NAME = "lapis-tools";
+const SUPPORTED_APP_TOOL_TRANSPORTS = new Set(["stdio-mcp", "http-mcp"]);
+export class DesktopAppToolBridge {
+    host;
+    #records = new Map();
+    #listeners = new Set();
+    #unsubscribeApprovals;
+    #subscribedBridge = null;
+    #unsubscribeCall;
+    #unsubscribeCancel;
+    constructor(host) {
+        this.host = host;
+        this.#unsubscribeApprovals = host.approvals.subscribe((request, bindingId) => {
+            const record = this.#records.get(bindingId);
+            const active = record ? [...record.calls.values()].at(-1) : undefined;
+            this.#emit(bindingId, {
+                type: "permission.request",
+                request,
+                ...(record && active
+                    ? { source: nextSource(record, active) }
+                    : {}),
+            });
+        });
+    }
+    async prepare(input) {
+        if (this.#records.has(input.agentBindingId)) {
+            throw new Error(`App tool bridge already exists: ${input.agentBindingId}`);
+        }
+        const bridge = getNativeDesktopBridge();
+        const hostCapable = supportsAppTools();
+        const runtimeCapable = input.runtimeSupportsAppTools;
+        const descriptor = this.host.createSession({
+            ...input,
+            runtimeSupportsAppTools: runtimeCapable && hostCapable,
+        });
+        const record = {
+            bindingId: input.agentBindingId,
+            calls: new Map(),
+        };
+        this.#records.set(input.agentBindingId, record);
+        if (!runtimeCapable) {
+            return withStatus(descriptor, "runtime-unavailable", "The selected agent runtime does not support application tools.");
+        }
+        if (!hostCapable || !bridge?.onAgentToolCall || !bridge.onAgentToolCancel) {
+            return withStatus(descriptor, "host-upgrade-required", "Application tools require an agent host with protocol v3 support.");
+        }
+        if (descriptor.tools.length === 0) {
+            return withStatus(descriptor, "disabled");
+        }
+        this.#subscribeToBridge(bridge);
+        try {
+            const opened = await bridge.invoke("desktop_agent_tools_open", {
+                bindingId: descriptor.agentBindingId,
+                conversationId: descriptor.conversationId,
+                descriptors: descriptor.tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                    effect: tool.effect,
+                })),
+            });
+            record.bridge = bridge;
+            record.bridgeId = opened.bridgeId;
+            return Object.freeze({
+                ...descriptor,
+                bridgeId: opened.bridgeId,
+                status: "available",
+            });
+        }
+        catch (error) {
+            this.#records.delete(input.agentBindingId);
+            this.host.closeBinding(input.agentBindingId);
+            throw error;
+        }
+    }
+    respondToApproval(requestId, decision) {
+        return this.host.approvals.respond(requestId, decision);
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async closeBinding(bindingId) {
+        const record = this.#records.get(bindingId);
+        this.#records.delete(bindingId);
+        for (const call of record?.calls.values() ?? [])
+            call.abort.abort();
+        record?.calls.clear();
+        this.host.closeBinding(bindingId);
+        if (record?.bridge && record.bridgeId) {
+            await record.bridge
+                .invoke("desktop_agent_tools_close", { bridgeId: record.bridgeId })
+                .catch(() => undefined);
+        }
+    }
+    async close() {
+        for (const bindingId of [...this.#records.keys()]) {
+            await this.closeBinding(bindingId);
+        }
+        this.#unsubscribeApprovals();
+        this.#unsubscribeCall?.();
+        this.#unsubscribeCancel?.();
+        this.#listeners.clear();
+        this.#subscribedBridge = null;
+    }
+    #subscribeToBridge(bridge) {
+        if (this.#subscribedBridge === bridge)
+            return;
+        this.#unsubscribeCall?.();
+        this.#unsubscribeCancel?.();
+        this.#subscribedBridge = bridge;
+        this.#unsubscribeCall = bridge.onAgentToolCall?.((call) => {
+            void this.#handleCall(call);
+        });
+        this.#unsubscribeCancel = bridge.onAgentToolCancel?.((cancel) => {
+            this.#handleCancel(cancel);
+        });
+    }
+    async #handleCall(call) {
+        const record = this.#records.get(call.bindingId);
+        if (!record || record.bridgeId !== call.bridgeId || !record.bridge)
+            return;
+        if (record.calls.has(call.callId))
+            return;
+        const active = {
+            abort: new AbortController(),
+            runId: `app-tool-${call.callId}`,
+            sequence: 0,
+        };
+        record.calls.set(call.callId, active);
+        this.#emit(call.bindingId, {
+            type: "tool.start",
+            id: call.callId,
+            name: call.name,
+            server: APP_TOOL_MCP_SERVER_NAME,
+            input: call.input,
+            source: nextSource(record, active),
+        });
+        try {
+            const result = await this.host.invoke(call.bindingId, {
+                runId: active.runId,
+                toolCallId: call.callId,
+                name: call.name,
+                input: call.input,
+            }, active.abort.signal);
+            await record.bridge.invoke("desktop_agent_tools_respond", {
+                bridgeId: call.bridgeId,
+                callId: call.callId,
+                result,
+            });
+            this.#emit(call.bindingId, {
+                type: "tool.end",
+                id: call.callId,
+                name: call.name,
+                server: APP_TOOL_MCP_SERVER_NAME,
+                output: result,
+                source: nextSource(record, active),
+            });
+        }
+        catch (error) {
+            const normalized = normalizeExecutionError(error);
+            await record.bridge
+                .invoke("desktop_agent_tools_respond", {
+                bridgeId: call.bridgeId,
+                callId: call.callId,
+                error: normalized,
+            })
+                .catch(() => undefined);
+            this.#emit(call.bindingId, {
+                type: "tool.end",
+                id: call.callId,
+                name: call.name,
+                server: APP_TOOL_MCP_SERVER_NAME,
+                error: normalized,
+                source: nextSource(record, active),
+            });
+        }
+        finally {
+            record.calls.delete(call.callId);
+        }
+    }
+    #handleCancel(cancel) {
+        const record = this.#records.get(cancel.bindingId);
+        if (!record || record.bridgeId !== cancel.bridgeId)
+            return;
+        record.calls.get(cancel.callId)?.abort.abort();
+    }
+    #emit(bindingId, event) {
+        for (const listener of this.#listeners)
+            listener({ bindingId, event });
+    }
+}
+function supportsAppTools() {
+    const capability = getNativeDesktopCapability("agent-runtime");
+    const protocolVersion = Number(capability?.details?.protocolVersion ?? 0);
+    const transport = String(capability?.details?.appTools ?? "");
+    return (capability?.status === "available" &&
+        protocolVersion >= 3 &&
+        SUPPORTED_APP_TOOL_TRANSPORTS.has(transport));
+}
+function withStatus(descriptor, status, unavailableReason) {
+    return Object.freeze({ ...descriptor, status, unavailableReason });
+}
+function nextSource(record, active) {
+    active.sequence += 1;
+    return {
+        sessionId: record.bridgeId ?? record.bindingId,
+        runId: active.runId,
+        sequence: active.sequence,
+    };
+}
+function normalizeExecutionError(error) {
+    if (error instanceof AppToolExecutionError) {
+        return { code: error.code, message: error.message };
+    }
+    return {
+        code: "execution_failed",
+        message: "Application tool execution failed.",
+    };
+}

package/dist/tools/mcp-server-registry.d.ts

@@ -0,0 +1,7 @@
+import type { McpServerContribution } from "../core/types";
+export declare const APP_TOOL_MCP_SERVER_NAME = "lapis-tools";
+export interface McpServerContributionRegistry {
+    register(contribution: McpServerContribution): () => void;
+    list(): McpServerContribution[];
+}
+export declare function createMcpServerContributionRegistry(initial?: McpServerContribution[]): McpServerContributionRegistry;