@parlor/agent-host 0.0.0-stage → 0.1.0

package/dist/turn.js

@@ -0,0 +1,650 @@
+import { mkdir } from "node:fs/promises";
+import { answerStatement, checkPairingProof, deviceCommitment, vouchStatement, signedPrompt, statementBytes, verifyStatement, } from "@parlor/auth";
+import { canonicalBytes, encodeBase64url } from "@parlor/capabilities/encoding";
+import { ActionError, asId } from "@parlor/core";
+import { SessionRefused, } from "./acp.js";
+import { finishFold, foldUpdate, startFold } from "./fold.js";
+import { logEvent } from "./log.js";
+import { appServerOf, computerName } from "./naming.js";
+import { approvalFor, isAppTool, presenceDueAt } from "./policy.js";
+import { agentEnvironment } from "./shell-path.js";
+export const PROMPT_MAX_AGE_MS = 10 * 60_000;
+/** A vouch is bound to one device's keys, so it may wait for that device's first prompt. */
+const VOUCH_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
+const SIGNAL_POLL_MS = 500;
+const MAX_APPEND_ITEMS = 64;
+const APPEND_RETRY_BASE_MS = 250;
+const APPEND_RETRY_MAX_MS = 4_000;
+const MIN_LEASE_MS = 1_000;
+const CANCEL_SETTLE_MS = 5_000;
+const QUESTION_CHOICES = [
+    { id: "accept", label: "Submit", effect: "allow_once" },
+    { id: "decline", label: "Decline", effect: "reject_once" },
+];
+class AgentExited extends Error {
+    exit;
+    name = "AgentExited";
+    constructor(exit) {
+        super("The agent exited.");
+        this.exit = exit;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class LeaseLapsed extends Error {
+    name = "LeaseLapsed";
+}
+function lapseAfter(ms) {
+    let timer;
+    const lapsed = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new LeaseLapsed("The turn's lease lapsed.")), ms);
+    });
+    lapsed.catch(() => undefined);
+    return { lapsed, cancel: () => clearTimeout(timer) };
+}
+async function settlesWithin(work, ms) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([work.then(() => true), late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function promptMaxAgeMs() {
+    const lowered = Number(process.env.PARLOR_HOST_PROMPT_MAX_AGE_MS);
+    return lowered > 0 ? Math.min(lowered, PROMPT_MAX_AGE_MS) : PROMPT_MAX_AGE_MS;
+}
+const hex = async (bytes) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)))]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+const fingerprint = (device) => encodeBase64url(canonicalBytes({ signing: device.signingKey, presence: device.presenceKey ?? null }));
+function exitDetail(exit) {
+    if (exit.kind === "killed")
+        return "stopped by this computer";
+    const last = exit.stderrTail.trim().split("\n").at(-1)?.slice(0, 300);
+    return [`exit code ${exit.code ?? "none"}`, last].filter(Boolean).join(": ");
+}
+function askBody(ask, approval) {
+    const body = ask.kind === "permission"
+        ? {
+            question: ask.title,
+            choices: ask.options.map((option) => ({ ...option })),
+        }
+        : {
+            question: ask.message,
+            choices: QUESTION_CHOICES.map((choice) => ({ ...choice })),
+            form: { ...ask.schema },
+        };
+    return approval ? { ...body, approval } : body;
+}
+function answerOf(pending, body) {
+    if (pending.ask.kind === "question") {
+        if (body.choice === "accept")
+            return { kind: "values", values: { ...body.values } };
+        return { kind: "declined" };
+    }
+    if (body.choice === "declined")
+        return { kind: "declined" };
+    return pending.ask.options.some((option) => option.id === body.choice)
+        ? { kind: "selected", optionId: body.choice }
+        : undefined;
+}
+/**
+ * Runs one claimed turn to its outcome and reports it with `hostFinish`: where the
+ * claimed prompt, the agent's updates, the user's answers and stop, and the local policy meet.
+ */
+export async function runTurn(claimed, deps) {
+    const { link, pool } = deps;
+    const { calls } = link.api;
+    const grant = link.grant;
+    const origin = grant.appOrigin;
+    const appServer = appServerOf(grant.appName);
+    const agentId = claimed.agent.agentId;
+    const threadId = claimed.id;
+    const turnId = claimed.turnId;
+    let fold = startFold(turnId);
+    let proxy;
+    let lost = false;
+    const lostOver = new AbortController();
+    const markLost = () => {
+        lost = true;
+        lostOver.abort();
+    };
+    const lostPromise = new Promise((resolve) => lostOver.signal.addEventListener("abort", () => resolve("lost"), { once: true }));
+    const leaseMs = Math.max(MIN_LEASE_MS, claimed.leaseUntil - deps.now());
+    let cancelled = false;
+    let lastWrite = deps.now();
+    let appending = Promise.resolve();
+    const pending = new Map();
+    const settle = (id, answer) => {
+        const waiting = pending.get(id);
+        if (!waiting)
+            return;
+        pending.delete(id);
+        waiting.dialog.abort();
+        waiting.resolve(answer);
+    };
+    const settleAll = () => {
+        for (const id of [...pending.keys()])
+            settle(id, { kind: "cancelled" });
+    };
+    const nextId = () => {
+        const id = asId("item", `${turnId}.${fold.nextId}`);
+        fold = { ...fold, nextId: fold.nextId + 1 };
+        return id;
+    };
+    const untilLeaseLapses = async (call) => {
+        const lease = lapseAfter(leaseMs);
+        try {
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    return await Promise.race([call(), lease.lapsed]);
+                }
+                catch (error) {
+                    if (error instanceof ActionError || error instanceof LeaseLapsed)
+                        throw error;
+                    await Promise.race([
+                        sleep(Math.min(APPEND_RETRY_BASE_MS * 2 ** attempt, APPEND_RETRY_MAX_MS)),
+                        lease.lapsed,
+                    ]);
+                }
+            }
+        }
+        finally {
+            lease.cancel();
+        }
+    };
+    const send = async (items) => {
+        const renewed = await untilLeaseLapses(() => calls.call("hostAppend", { turnId, items }));
+        lastWrite = deps.now();
+        proxy?.renew(renewed.token);
+        logEvent("host_append", { turnId, itemIds: items.map((item) => item.id) });
+    };
+    const write = (items) => {
+        const batch = [...items];
+        appending = appending.then(async () => {
+            if (lost)
+                return;
+            try {
+                if (batch.length === 0) {
+                    await send([]);
+                    return;
+                }
+                for (let at = 0; at < batch.length; at += MAX_APPEND_ITEMS) {
+                    await send(batch.slice(at, at + MAX_APPEND_ITEMS));
+                }
+            }
+            catch {
+                markLost();
+            }
+        });
+        return appending;
+    };
+    const event = (name, detail, itemId) => write([
+        {
+            id: nextId(),
+            kind: "event",
+            body: {
+                event: name,
+                ...(detail ? { detail: detail.slice(0, 500) } : {}),
+                ...(itemId ? { itemId } : {}),
+            },
+        },
+    ]);
+    const finish = async (outcome) => {
+        await appending;
+        proxy?.end();
+        if (lost)
+            return { state: "failed", reason: "host_lost" };
+        try {
+            await untilLeaseLapses(() => calls.call("hostFinish", { turnId, outcome }));
+        }
+        catch (error) {
+            if (error instanceof LeaseLapsed)
+                return { state: "failed", reason: "host_lost" };
+            if (!(error instanceof ActionError && error.code === "forbidden"))
+                throw error;
+        }
+        return outcome;
+    };
+    const fail = async (reason, name, detail) => {
+        await event(name, detail);
+        return finish({ state: "failed", reason });
+    };
+    const verifyPrompt = async (signed, pinned, requirePresence) => {
+        const outcome = await verifyStatement(signed, pinned, {
+            requirePresence,
+            now: deps.now(),
+            maxAgeMs: promptMaxAgeMs(),
+        });
+        logEvent("statement_verified", {
+            kind: "prompt",
+            deviceId: pinned.deviceId,
+            outcome,
+            sha256: await hex(statementBytes(signed.statement)),
+        });
+        return outcome;
+    };
+    const refuse = async (reason, name, detail) => ({ outcome: await fail(reason, name, detail) });
+    /** A vouch counts when a device pinned here signed it with presence, for exactly these keys. */
+    const vouchedFor = async (keys) => {
+        if (!keys.vouches?.length)
+            return undefined;
+        const commitment = await deviceCommitment(origin, keys.id, keys.signingKey, keys.presenceKey?.publicKey);
+        for (const vouch of keys.vouches) {
+            if (vouch.commitment !== commitment)
+                continue;
+            const voucher = await deps.trust.get(origin, vouch.voucher);
+            if (!voucher?.presenceKey)
+                continue;
+            const outcome = await verifyStatement({
+                statement: vouchStatement(origin, vouch.voucher, keys.id, commitment, vouch.at),
+                deviceId: voucher.deviceId,
+                signature: vouch.signature,
+            }, voucher, { requirePresence: true, now: deps.now(), maxAgeMs: VOUCH_MAX_AGE_MS });
+            logEvent("vouch_verified", { deviceId: keys.id, voucher: vouch.voucher, outcome });
+            if (outcome !== "valid")
+                continue;
+            return {
+                deviceId: keys.id,
+                signingKey: keys.signingKey,
+                presenceKey: keys.presenceKey,
+                name: keys.name,
+                platform: keys.platform,
+                approvedAt: deps.now(),
+                via: "vouched",
+                voucher: vouch.voucher,
+            };
+        }
+        return undefined;
+    };
+    const pinVouched = async (device) => {
+        await deps.trust.pin(origin, device);
+        logEvent("device_trusted", { deviceId: device.deviceId, via: "vouched" });
+        deps.prompter.deviceLinked?.({
+            appName: grant.appName,
+            device: device.name ?? "A device",
+        });
+    };
+    /** Moves the device's last presence check forward; reported so its devices know when the next is due. */
+    const confirmedPresence = async (device, at) => {
+        if (at <= (device.presenceAt ?? device.approvedAt))
+            return;
+        await deps.trust.pin(origin, { ...device, presenceAt: at });
+    };
+    const unlinked = `Link this device to use your agents on ${computerName()}: open the Agent sidebar on it.`;
+    const admit = async () => {
+        const signed = await signedPrompt(origin, claimed.prompt);
+        if (!signed) {
+            return refuse("device_rejected", "turn_failed", `Update ${grant.appName} to send messages to ${computerName()}: this version does not sign them.`);
+        }
+        const known = await deps.trust.get(origin, signed.deviceId);
+        const keys = claimed.device;
+        if (known && !keys) {
+            await deps.trust.forget(origin, known.deviceId);
+            return refuse("device_rejected", "device_rejected", "This device is no longer registered.");
+        }
+        if (!keys || keys.id !== signed.deviceId) {
+            return refuse("signature_invalid", "turn_failed", "The account has no such device.");
+        }
+        if (known && fingerprint(known) !== fingerprint(keys)) {
+            return refuse("signature_invalid", "turn_failed", "This device's keys changed.");
+        }
+        const pinned = known ?? {
+            deviceId: keys.id,
+            signingKey: keys.signingKey,
+            presenceKey: keys.presenceKey,
+        };
+        const due = known && presenceDueAt(deps.policy, known);
+        const outcome = await verifyPrompt(signed, pinned, due !== undefined && signed.statement.at > due);
+        if (outcome === "stale") {
+            return { outcome: await finish({ state: "failed", reason: "prompt_expired" }) };
+        }
+        if (outcome === "presence_required") {
+            return refuse("device_rejected", "turn_failed", `Confirm it's you to keep using your agents on ${computerName()} from this device: send again and use Face ID or Touch ID.`);
+        }
+        if (outcome !== "valid") {
+            return refuse("signature_invalid", "turn_failed", "This prompt's signature did not check out.");
+        }
+        if (known) {
+            if (signed.signature.presence === "user") {
+                await confirmedPresence(known, signed.statement.at);
+            }
+            return { device: known };
+        }
+        const proof = claimed.prompt.body.signed?.pairing;
+        const secret = proof ? await deps.pairing?.secret() : undefined;
+        if (proof &&
+            secret &&
+            (await checkPairingProof(secret, proof, keys.id, keys.signingKey))) {
+            const device = {
+                ...pinned,
+                name: keys.name,
+                platform: keys.platform,
+                approvedAt: deps.now(),
+                via: "pairing",
+            };
+            await deps.trust.pin(origin, device);
+            await deps.pairing?.forget();
+            logEvent("device_trusted", { deviceId: keys.id, via: "pairing" });
+            return { device };
+        }
+        const vouched = await vouchedFor(keys);
+        if (vouched) {
+            await pinVouched(vouched);
+            return { device: vouched };
+        }
+        return refuse("device_rejected", "device_rejected", unlinked);
+    };
+    const proceed = async (device) => {
+        const profile = deps.profiles.find((candidate) => candidate.id === agentId);
+        if (!profile) {
+            return fail("agent_unavailable", "turn_failed", `This computer has no agent "${agentId}".`);
+        }
+        let live = pool.session(grant, threadId, agentId);
+        let connection = pool.process(origin, agentId);
+        const fresh = live === undefined;
+        if (live) {
+            proxy = live.proxy;
+            proxy.begin(claimed.token);
+        }
+        else {
+            const switched = deps.profiles.some((other) => other.id !== agentId && pool.session(grant, threadId, other.id) !== undefined);
+            if (switched)
+                await event("agent_switched", profile.name);
+            try {
+                connection = await pool.launch(origin, agentId, async (signal) => {
+                    await mkdir(grant.workspace, { recursive: true, mode: 0o700 });
+                    return deps.launcher.launch(profile, {
+                        cwd: grant.workspace,
+                        env: await agentEnvironment(),
+                        signal,
+                    });
+                });
+                proxy = deps.proxy.open(appServer, origin);
+                proxy.begin(claimed.token);
+                const session = await connection.openSession({
+                    cwd: grant.workspace,
+                    mcpServers: [proxy.server],
+                    resume: await pool.resumable(grant, threadId, agentId),
+                    pinAskMode: true,
+                    strictAsk: deps.policy.answers !== "off",
+                });
+                live = { session, proxy };
+                pool.remember(grant, threadId, agentId, live);
+            }
+            catch (error) {
+                proxy?.dispose();
+                proxy = undefined;
+                if (error instanceof SessionRefused && error.leftOpen) {
+                    await pool.drop(origin, agentId);
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return fail("agent_unavailable", "turn_failed", message);
+            }
+        }
+        const { session } = live;
+        const exited = connection.exited.then((exit) => {
+            throw new AgentExited(exit);
+        });
+        exited.catch(() => undefined);
+        const text = claimed.prompt.body.text;
+        const blocks = [
+            {
+                kind: "text",
+                text: fresh && !session.resumed ? `${claimed.context}\n\n${text}` : text,
+            },
+        ];
+        const fromThisComputer = grant.dev === true || device?.via === "pairing";
+        if (!fromThisComputer) {
+            deps.prompter.turnStarted({
+                appName: grant.appName,
+                device: device?.name ?? claimed.device?.name ?? "the app",
+                agent: profile.name,
+                preview: text.slice(0, 80),
+            });
+        }
+        const turnOver = new AbortController();
+        const cancel = () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            void session.cancel();
+            settleAll();
+            turnOver.abort();
+        };
+        const ask = async (question) => {
+            if (cancelled)
+                return { kind: "cancelled" };
+            if (question.kind === "permission" && isAppTool(question, appServer)) {
+                const allow = question.options.find((option) => option.effect === "allow_once");
+                if (allow)
+                    return { kind: "selected", optionId: allow.id };
+            }
+            const wanted = approvalFor(deps.policy, question);
+            const approval = wanted === "presence" && device && !device.presenceKey ? "computer" : wanted;
+            const id = nextId();
+            const dialog = new AbortController();
+            const answered = new Promise((resolve) => pending.set(id, { ask: question, approval, dialog, resolve }));
+            await write([{ id, kind: "ask", body: askBody(question, approval) }]);
+            if (approval === "computer") {
+                const choices = question.kind === "permission" ? question.options : QUESTION_CHOICES;
+                void deps.prompter
+                    .answerHere({
+                    appName: grant.appName,
+                    agent: profile.name,
+                    question: question.kind === "permission" ? question.title : question.message,
+                    choices,
+                    signal: dialog.signal,
+                })
+                    .then((choice) => {
+                    const waiting = pending.get(id);
+                    if (!waiting)
+                        return;
+                    const answer = choice === undefined ? undefined : answerOf(waiting, { askId: id, choice });
+                    if (choice !== undefined && answer) {
+                        void write([
+                            {
+                                id: nextId(),
+                                kind: "event",
+                                body: { event: "answered_on_computer", itemId: id, choice },
+                            },
+                        ]);
+                    }
+                    settle(id, answer ?? { kind: "cancelled" });
+                });
+            }
+            return answered;
+        };
+        const rejected = (reason) => ({ kind: "rejected", reason });
+        const verdictOf = async (waiting, item, devices) => {
+            if (waiting.approval === "computer") {
+                return rejected("This question is answered on the computer.");
+            }
+            if (deps.policy.deviceApproval !== "local" && waiting.approval !== "presence") {
+                return { kind: "accepted" };
+            }
+            const { signed, askId, choice, values } = item.body;
+            const pinned = signed ? await deps.trust.get(origin, signed.deviceId) : undefined;
+            const listed = signed
+                ? devices.find((keys) => keys.id === signed.deviceId)
+                : undefined;
+            const known = pinned ??
+                (listed && {
+                    deviceId: listed.id,
+                    signingKey: listed.signingKey,
+                    presenceKey: listed.presenceKey,
+                });
+            if (!signed || !known) {
+                logEvent("statement_verified", {
+                    kind: "answer",
+                    deviceId: signed?.deviceId,
+                    outcome: "invalid",
+                });
+                return rejected("This device cannot answer here.");
+            }
+            const statement = await answerStatement(origin, { threadId: item.threadId, askId, choice, ...(values ? { values } : {}) }, signed.at);
+            const outcome = await verifyStatement({ statement, deviceId: signed.deviceId, signature: signed.signature }, known, {
+                requirePresence: waiting.approval === "presence",
+                now: deps.now(),
+                maxAgeMs: PROMPT_MAX_AGE_MS,
+            });
+            logEvent("statement_verified", {
+                kind: "answer",
+                deviceId: signed.deviceId,
+                outcome,
+                sha256: await hex(statementBytes(statement)),
+            });
+            if (outcome === "presence_required") {
+                return rejected("This answer needs a presence check.");
+            }
+            if (outcome !== "valid")
+                return rejected("This answer's signature did not check out.");
+            if (pinned && signed.signature.presence === "user") {
+                await confirmedPresence(pinned, signed.at);
+            }
+            return pinned || !listed
+                ? { kind: "accepted" }
+                : { kind: "unpinned", device: listed };
+        };
+        const deliver = (waiting, item, verdict) => {
+            const answer = verdict.kind === "accepted" ? answerOf(waiting, item.body) : undefined;
+            if (!answer) {
+                void event("answer_rejected", verdict.kind === "rejected"
+                    ? verdict.reason
+                    : "That is not one of the choices.", item.id);
+                return;
+            }
+            settle(item.body.askId, answer);
+        };
+        const admitAnswer = async (waiting, item, devices) => {
+            const verdict = await verdictOf(waiting, item, devices);
+            if (verdict.kind !== "unpinned") {
+                deliver(waiting, item, verdict);
+                return;
+            }
+            const vouched = await vouchedFor(verdict.device);
+            if (!vouched) {
+                deliver(waiting, item, rejected(unlinked));
+                return;
+            }
+            await pinVouched(vouched);
+            deliver(waiting, item, { kind: "accepted" });
+        };
+        let afterSeq = claimed.prompt.seq;
+        const signalsOver = new AbortController();
+        const signalsEnded = new Promise((resolve) => signalsOver.signal.addEventListener("abort", () => resolve("ended"), {
+            once: true,
+        }));
+        const signals = async () => {
+            for (;;) {
+                if ((await Promise.race([sleep(SIGNAL_POLL_MS), signalsEnded])) === "ended")
+                    return;
+                let batches;
+                try {
+                    const fetched = await Promise.race([
+                        calls.call("hostSignals", { turns: [{ turnId, afterSeq }] }),
+                        signalsEnded,
+                    ]);
+                    if (fetched === "ended")
+                        return;
+                    batches = fetched;
+                }
+                catch {
+                    continue;
+                }
+                for (const batch of batches) {
+                    for (const item of batch.items) {
+                        if (signalsOver.signal.aborted)
+                            return;
+                        afterSeq = Math.max(afterSeq, item.seq);
+                        if (item.kind === "cancel") {
+                            cancel();
+                            continue;
+                        }
+                        const waiting = pending.get(item.body.askId);
+                        if (waiting)
+                            await admitAnswer(waiting, item, batch.devices ?? []);
+                    }
+                }
+            }
+        };
+        let stop;
+        let failure;
+        const prompted = session.prompt(blocks, {
+            update: (update) => {
+                const step = foldUpdate(fold, update, appServer);
+                fold = step.fold;
+                if (step.frames.length > 0)
+                    link.api.stream({ turnId, frames: step.frames });
+                if (step.closed.length > 0)
+                    void write(step.closed);
+            },
+            ask,
+        });
+        prompted.catch(() => undefined);
+        const signalsRan = signals().catch(() => undefined);
+        try {
+            stop = await Promise.race([prompted, exited, lostPromise]);
+            if (stop === "lost") {
+                signalsOver.abort();
+                proxy?.end();
+                const settled = await settlesWithin(Promise.allSettled([session.cancel(), prompted]), CANCEL_SETTLE_MS);
+                if (!settled)
+                    await pool.drop(origin, agentId);
+            }
+        }
+        catch (error) {
+            failure =
+                error instanceof AgentExited
+                    ? error
+                    : await Promise.race([
+                        exited.catch((exit) => exit),
+                        sleep(1_000).then(() => error instanceof Error ? error : new Error(String(error))),
+                    ]);
+        }
+        finally {
+            signalsOver.abort();
+            settleAll();
+            turnOver.abort();
+        }
+        await signalsRan;
+        const stopped = failure !== undefined || cancelled || stop === "cancelled";
+        const final = finishFold(fold, stopped);
+        fold = final.fold;
+        void write(final.closed);
+        if (failure) {
+            await pool.drop(origin, agentId);
+            const detail = failure instanceof AgentExited ? exitDetail(failure.exit) : failure.message;
+            return fail("agent_exited", "agent_exited", detail);
+        }
+        if (lost) {
+            proxy?.end();
+            return { state: "failed", reason: "host_lost" };
+        }
+        return finish(stopped
+            ? { state: "cancelled" }
+            : { state: "done", stopReason: stop });
+    };
+    const renewEveryMs = Math.max(1_000, (claimed.leaseUntil - deps.now()) / 2);
+    const renewal = setInterval(() => {
+        if (deps.now() - lastWrite >= renewEveryMs)
+            void write([]);
+    }, renewEveryMs / 4);
+    try {
+        if (deps.policy.deviceApproval === "local") {
+            const admission = await admit();
+            if ("outcome" in admission)
+                return admission.outcome;
+            return await proceed(admission.device);
+        }
+        return await proceed(undefined);
+    }
+    finally {
+        clearInterval(renewal);
+    }
+}
+//# sourceMappingURL=turn.js.map