stageflow 0.36.0 → 0.40.0

package/dist/agents/trace.js

@@ -0,0 +1,29 @@
+import { randomBytes } from "node:crypto";
+import { redactSecrets } from "../agent/streamLogRedact.js";
+/**
+ * Apply the revision's capture mode to a span before it is stored:
+ * `off` records nothing, `metadata` drops prompt/argument/result bodies, and
+ * `full` keeps them after secret redaction. Redaction happens here, before
+ * storage, so export never sees an unredacted body.
+ */
+export function prepareSpan(capture, draft) {
+    if (capture === "off")
+        return null;
+    const full = capture === "full";
+    return {
+        id: randomBytes(8).toString("hex"),
+        turnId: draft.turnId,
+        parentSpanId: draft.parentSpanId ?? null,
+        name: draft.name,
+        kind: draft.kind,
+        status: draft.status,
+        startedAt: draft.startedAt.toISOString(),
+        endedAt: draft.endedAt?.toISOString() ?? null,
+        durationMs: draft.endedAt ? Math.max(0, draft.endedAt.getTime() - draft.startedAt.getTime()) : null,
+        inputTokens: draft.usage?.inputTokens ?? null,
+        outputTokens: draft.usage?.outputTokens ?? null,
+        attributes: draft.attributes ?? {},
+        inputText: full && draft.input !== undefined ? redactSecrets(draft.input) : null,
+        outputText: full && draft.output !== undefined ? redactSecrets(draft.output) : null,
+    };
+}

package/dist/agents/turnLifecycle.d.ts

@@ -0,0 +1,72 @@
+import type { ApprovalBroker, ApprovalOutcome } from "./approvalBroker.js";
+import type { AgentApproval, AgentStore, ApprovalActor, SessionStatus, TurnStatus } from "./store.js";
+/** Turn statuses nothing can leave. */
+export type TerminalTurnStatus = Exclude<TurnStatus, "running" | "waiting">;
+export declare function isTerminalTurnStatus(status: TurnStatus): status is TerminalTurnStatus;
+export type FinishInput = {
+    status: TerminalTurnStatus;
+    errorCode?: string | null;
+    /** The assistant's reply, written with the turn so the transcript and the outcome never disagree. */
+    assistant?: {
+        id: string;
+        author: string;
+        text: string;
+    };
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    costUsd?: number | null;
+    evalScores?: Array<{
+        metric: string;
+        score: number;
+    }>;
+    sessionStatus?: SessionStatus;
+};
+/**
+ * The single owner of what may happen to a turn, its session and its approval. Every change of those statuses goes
+ * through here, so the rows and the broker wake-up move together and an illegal move is refused instead of applied.
+ *
+ *   turn:     running <-> waiting -> succeeded | failed | cancelled      (terminal states are final)
+ *   approval: pending -> approved | denied | expired                     (decided approvals are final)
+ *   session:  open -> running <-> waiting -> open                        (follows its one active turn)
+ *
+ * The methods are synchronous database work; callers serialise them (AgentService runs them in its exclusive section).
+ */
+export declare class TurnLifecycle {
+    private readonly store;
+    private readonly broker;
+    private readonly nowIso;
+    constructor(store: AgentStore, broker: ApprovalBroker, nowIso: () => string);
+    /** The turn is paused on a person. Refused (false) unless it is running; an already decided approval returns its outcome instead. */
+    wait(turnId: string, approvalId: string): "waiting" | ApprovalOutcome | "inactive";
+    /** The decision arrived (or the wait ended): back to running. No-op unless the turn is waiting. */
+    resume(turnId: string): boolean;
+    /**
+     * End a turn: succeeded, failed or cancelled. Writes the reply, the outcome, scores and session status together, and
+     * closes any approval the turn still has open so it can no longer be approved. Returns false (and changes nothing)
+     * when the turn is unknown or already over.
+     */
+    finish(turnId: string, input: FinishInput): boolean;
+    /** The Host restarted: nothing can resume running turns, so they fail and their approvals close. */
+    interruptedByRestart(): number;
+    /** Close one open approval without a decision (its turn was stopped). Returns false when it was already decided. */
+    closeApproval(approvalId: string): boolean;
+    /** Expire every approval past its deadline and wake whoever waits on it. */
+    expireDue(): void;
+    /**
+     * Record a decision on the session's pending approval. An approval whose turn is already over is closed instead of
+     * approved, so a late click cannot run an action nobody is waiting for or pre-approve a later identical call.
+     * Returns the decided approval, or "stale" when the approval had to be closed.
+     */
+    decide(pending: AgentApproval, decision: "approve" | "deny", actor: ApprovalActor): {
+        approval: AgentApproval;
+    } | "stale";
+    /**
+     * A channel reply that could not be delivered turns a succeeded turn into a failure, and one that finally arrives puts
+     * it right. Only that one marker moves; a turn that is unfinished, cancelled or failed for another reason is left alone.
+     */
+    replyDelivery(turnId: string, delivered: boolean): void;
+    /** Delivery sends a restart cut off: their turns wait for a person. Only finished (succeeded) turns are marked. */
+    replyUnconfirmed(turnIds: string[]): void;
+}

package/dist/agents/turnLifecycle.js

@@ -0,0 +1,157 @@
+export function isTerminalTurnStatus(status) {
+    return status !== "running" && status !== "waiting";
+}
+/**
+ * The single owner of what may happen to a turn, its session and its approval. Every change of those statuses goes
+ * through here, so the rows and the broker wake-up move together and an illegal move is refused instead of applied.
+ *
+ *   turn:     running <-> waiting -> succeeded | failed | cancelled      (terminal states are final)
+ *   approval: pending -> approved | denied | expired                     (decided approvals are final)
+ *   session:  open -> running <-> waiting -> open                        (follows its one active turn)
+ *
+ * The methods are synchronous database work; callers serialise them (AgentService runs them in its exclusive section).
+ */
+export class TurnLifecycle {
+    store;
+    broker;
+    nowIso;
+    constructor(store, broker, nowIso) {
+        this.store = store;
+        this.broker = broker;
+        this.nowIso = nowIso;
+    }
+    /** The turn is paused on a person. Refused (false) unless it is running; an already decided approval returns its outcome instead. */
+    wait(turnId, approvalId) {
+        const turn = this.store.getTurn(turnId);
+        if (!turn || turn.status !== "running")
+            return "inactive";
+        const approval = this.store.getApproval(approvalId);
+        // Decided between the request and this call: do not park on a decision that already happened.
+        if (approval && approval.status !== "pending")
+            return approval.status;
+        this.store.transaction(() => {
+            this.store.setTurnStatus(turnId, "waiting");
+            this.store.updateSession(turn.sessionId, { status: "waiting" }, this.nowIso());
+        });
+        return "waiting";
+    }
+    /** The decision arrived (or the wait ended): back to running. No-op unless the turn is waiting. */
+    resume(turnId) {
+        const turn = this.store.getTurn(turnId);
+        if (!turn || turn.status !== "waiting")
+            return false;
+        this.store.transaction(() => {
+            this.store.setTurnStatus(turnId, "running");
+            this.store.updateSession(turn.sessionId, { status: "running" }, this.nowIso());
+        });
+        return true;
+    }
+    /**
+     * End a turn: succeeded, failed or cancelled. Writes the reply, the outcome, scores and session status together, and
+     * closes any approval the turn still has open so it can no longer be approved. Returns false (and changes nothing)
+     * when the turn is unknown or already over.
+     */
+    finish(turnId, input) {
+        const turn = this.store.getTurn(turnId);
+        if (!turn || isTerminalTurnStatus(turn.status))
+            return false;
+        const now = this.nowIso();
+        const closed = this.store.transaction(() => {
+            if (input.assistant && input.assistant.text.length > 0) {
+                this.store.appendMessage({
+                    id: input.assistant.id,
+                    sessionId: turn.sessionId,
+                    turnId,
+                    role: "assistant",
+                    author: input.assistant.author,
+                    text: input.assistant.text,
+                    createdAt: now,
+                });
+            }
+            this.store.finishTurn(turnId, {
+                status: input.status,
+                errorCode: input.errorCode ?? null,
+                inputTokens: input.usage?.inputTokens ?? null,
+                outputTokens: input.usage?.outputTokens ?? null,
+                costUsd: input.costUsd ?? null,
+                endedAt: now,
+            });
+            for (const score of input.evalScores ?? []) {
+                this.store.recordEvalScore({ turnId, metric: score.metric, score: score.score, recordedAt: now });
+            }
+            const ids = this.store.closePendingApprovalsOfTurn(turnId, now);
+            this.store.updateSession(turn.sessionId, { status: input.sessionStatus ?? "open" }, now);
+            return ids;
+        });
+        for (const approvalId of closed)
+            this.broker.settle(approvalId, "expired");
+        return true;
+    }
+    /** The Host restarted: nothing can resume running turns, so they fail and their approvals close. */
+    interruptedByRestart() {
+        return this.store.failInterruptedTurns(this.nowIso());
+    }
+    /** Close one open approval without a decision (its turn was stopped). Returns false when it was already decided. */
+    closeApproval(approvalId) {
+        const approval = this.store.getApproval(approvalId);
+        if (!approval || approval.status !== "pending")
+            return false;
+        this.store.decideApproval(approvalId, { status: "expired", decidedAt: this.nowIso(), actor: null });
+        this.broker.settle(approvalId, "expired");
+        return true;
+    }
+    /** Expire every approval past its deadline and wake whoever waits on it. */
+    expireDue() {
+        const now = this.nowIso();
+        for (const { approvalId, sessionId } of this.store.expireApprovals(now)) {
+            const session = this.store.getSession(sessionId);
+            if (session?.status === "waiting")
+                this.store.updateSession(sessionId, { status: "open" }, now);
+            this.broker.settle(approvalId, "expired");
+        }
+    }
+    /**
+     * Record a decision on the session's pending approval. An approval whose turn is already over is closed instead of
+     * approved, so a late click cannot run an action nobody is waiting for or pre-approve a later identical call.
+     * Returns the decided approval, or "stale" when the approval had to be closed.
+     */
+    decide(pending, decision, actor) {
+        const now = this.nowIso();
+        const turn = pending.turnId ? this.store.getTurn(pending.turnId) : undefined;
+        if (turn && isTerminalTurnStatus(turn.status)) {
+            this.closeApproval(pending.id);
+            return "stale";
+        }
+        const status = decision === "approve" ? "approved" : "denied";
+        this.store.transaction(() => {
+            this.store.decideApproval(pending.id, { status, decidedAt: now, actor });
+            if (decision === "approve")
+                this.store.markPayloadExecuted(pending.sessionId, pending.payloadHash, now);
+            this.store.updateSession(pending.sessionId, { status: "open" }, now);
+        });
+        this.broker.settle(pending.id, status);
+        return { approval: { ...pending, status, decidedAt: now, actor } };
+    }
+    /**
+     * A channel reply that could not be delivered turns a succeeded turn into a failure, and one that finally arrives puts
+     * it right. Only that one marker moves; a turn that is unfinished, cancelled or failed for another reason is left alone.
+     */
+    replyDelivery(turnId, delivered) {
+        const turn = this.store.getTurn(turnId);
+        if (!turn)
+            return;
+        const undelivered = turn.status === "failed" && turn.errorCode === "agent.reply_undelivered";
+        if (delivered) {
+            if (undelivered)
+                this.store.setTurnOutcome(turnId, "succeeded", null);
+        }
+        else if (turn.status === "succeeded") {
+            this.store.setTurnOutcome(turnId, "failed", "agent.reply_undelivered");
+        }
+    }
+    /** Delivery sends a restart cut off: their turns wait for a person. Only finished (succeeded) turns are marked. */
+    replyUnconfirmed(turnIds) {
+        for (const turnId of turnIds)
+            this.replyDelivery(turnId, false);
+    }
+}

package/dist/agents/webChat/publicChat.d.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AgentChatController } from "../chatTurn.js";
+import type { AgentService } from "../service.js";
+export type PublicChatOptions = {
+    service: AgentService;
+    chat: AgentChatController;
+    projectRoot: string;
+    /** Extra origins allowed to call the API from a browser (a page hosted elsewhere). Same-origin always works. */
+    allowedOrigins?: string[];
+    now?: () => number;
+    logError?: (message: string) => void;
+};
+/**
+ * The public, anonymous chat surface. The link slug is the credential; a visitor id the page keeps in
+ * the browser scopes conversations. Nothing here returns tool payloads, traces or other visitors' data.
+ */
+export declare class PublicWebChat {
+    private readonly options;
+    private readonly limiter;
+    private readonly resolved;
+    private readonly now;
+    constructor(options: PublicChatOptions);
+    /** True when `pathname` belongs to this surface (the caller then must not fall through). */
+    static owns(pathname: string): boolean;
+    handle(req: IncomingMessage, res: ServerResponse, method: string, pathname: string): Promise<boolean>;
+    private collection;
+    private threadView;
+    private ownedSession;
+    private send;
+    private resolve;
+    private visitorOf;
+    /** Messages and new conversations have their own budgets (`kind`); thread creation gets twice the message limit. */
+    private throttle;
+    private applyCors;
+    private json;
+}

package/dist/agents/webChat/publicChat.js

@@ -0,0 +1,290 @@
+import { isAgentError } from "../errors.js";
+import { BodyError, readJsonBody, writeFrame } from "../ndjson.js";
+import { SlidingWindowLimiter } from "./rateLimit.js";
+const SOURCE = "web";
+const MAX_THREADS = 50;
+const MAX_BODY_BYTES = 256 * 1024;
+const RESOLVE_TTL_MS = 1_000;
+const WAIT_POLL_MS = 1_000;
+const VISITOR_ID = /^[A-Za-z0-9_-]{16,64}$/;
+const FRIENDLY = {
+    "web_chat.unavailable": { status: 404, message: "This chat isn't available." },
+    "web_chat.rate_limited": { status: 429, message: "You're sending messages too quickly. Please wait a moment." },
+    "web_chat.message_too_long": { status: 413, message: "That message is too long." },
+    "web_chat.busy": { status: 409, message: "Still working on your last message." },
+    "web_chat.limit_reached": { status: 409, message: "This conversation has reached its limit. Start a new one." },
+    "web_chat.invalid": { status: 400, message: "That request wasn't understood." },
+    "web_chat.failed": { status: 500, message: "Something went wrong. Please try again." },
+};
+class WebChatError extends Error {
+    code;
+    retryAfterSec;
+    constructor(code, retryAfterSec, message) {
+        super(message ?? FRIENDLY[code]?.message ?? code);
+        this.code = code;
+        this.retryAfterSec = retryAfterSec;
+    }
+}
+function errorFrame(error) {
+    return {
+        type: "error",
+        code: error.code,
+        message: error.message,
+        ...(error.retryAfterSec !== undefined ? { retryAfterSec: error.retryAfterSec } : {}),
+    };
+}
+function toWebChatError(error) {
+    if (error instanceof WebChatError)
+        return error;
+    if (isAgentError(error)) {
+        if (error.code === "agent.limit_reached")
+            return new WebChatError("web_chat.limit_reached");
+        if (error.code === "agent.session_busy")
+            return new WebChatError("web_chat.busy");
+        if (error.code === "agent.disabled" || error.code === "agent.not_found" || error.code === "agent.archived") {
+            return new WebChatError("web_chat.unavailable");
+        }
+        if (error.code === "agent.guardrail_blocked") {
+            return new WebChatError("web_chat.failed", undefined, "I can't help with that. Try asking differently.");
+        }
+    }
+    return new WebChatError("web_chat.failed");
+}
+/**
+ * The public, anonymous chat surface. The link slug is the credential; a visitor id the page keeps in
+ * the browser scopes conversations. Nothing here returns tool payloads, traces or other visitors' data.
+ */
+export class PublicWebChat {
+    options;
+    limiter = new SlidingWindowLimiter();
+    resolved = new Map();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    /** True when `pathname` belongs to this surface (the caller then must not fall through). */
+    static owns(pathname) {
+        return pathname.startsWith("/api/public/chat/");
+    }
+    async handle(req, res, method, pathname) {
+        if (!PublicWebChat.owns(pathname))
+            return false;
+        this.applyCors(req, res);
+        if (method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return true;
+        }
+        try {
+            const parts = pathname.slice("/api/public/chat/".length).replace(/\/+$/, "").split("/");
+            const [slug = "", threads, threadId, messages] = parts;
+            const shapeOk = parts.length === 1 || (threads === "threads" && (parts.length === 2 || parts.length === 3 || (parts.length === 4 && messages === "messages")));
+            if (!shapeOk)
+                throw new WebChatError("web_chat.unavailable");
+            const target = await this.resolve(slug);
+            if (parts.length === 1) {
+                if (method !== "GET")
+                    throw new WebChatError("web_chat.invalid");
+                return this.json(res, 200, { agent: { name: target.definition.name, greeting: target.definition.greeting ?? null } });
+            }
+            const visitor = this.visitorOf(req);
+            if (parts.length === 2)
+                return this.collection(req, res, method, target, visitor);
+            const session = this.ownedSession(target, visitor, decodeURIComponent(threadId));
+            if (parts.length === 4) {
+                if (method !== "POST")
+                    throw new WebChatError("web_chat.invalid");
+                return await this.send(req, res, target, visitor, session);
+            }
+            if (method !== "GET")
+                throw new WebChatError("web_chat.invalid");
+            const detail = await this.options.service.getSession(this.options.projectRoot, session.id);
+            return this.json(res, 200, {
+                thread: this.threadView(detail.session),
+                status: detail.session.status === "running" || detail.session.status === "waiting" ? detail.session.status : "open",
+                messages: detail.messages.map((message) => ({ id: message.id, role: message.role, text: message.text, createdAt: message.createdAt })),
+            });
+        }
+        catch (error) {
+            const failure = toWebChatError(error);
+            if (failure.code === "web_chat.failed")
+                this.options.logError?.(`public web chat failed: ${error instanceof Error ? error.message : String(error)}`);
+            if (res.headersSent) {
+                if (!res.writableEnded)
+                    res.end(`${JSON.stringify(errorFrame(failure))}\n`);
+                return true;
+            }
+            if (failure.retryAfterSec !== undefined)
+                res.setHeader("Retry-After", String(failure.retryAfterSec));
+            const { type: _type, ...body } = errorFrame(failure);
+            return this.json(res, (FRIENDLY[failure.code] ?? FRIENDLY["web_chat.failed"]).status, body);
+        }
+    }
+    async collection(req, res, method, target, visitor) {
+        const { service, projectRoot } = this.options;
+        if (method === "GET") {
+            const sessions = service.listSessionsForRef(projectRoot, target.agentId, SOURCE, visitor, MAX_THREADS);
+            return this.json(res, 200, { threads: sessions.map((session) => this.threadView(session)) });
+        }
+        if (method !== "POST")
+            throw new WebChatError("web_chat.invalid");
+        this.throttle(target.definition.web_chat.slug ?? "", visitor, req, target, "thread");
+        const existing = service.listSessionsForRef(projectRoot, target.agentId, SOURCE, visitor, MAX_THREADS);
+        if (existing.length >= MAX_THREADS) {
+            throw new WebChatError("web_chat.limit_reached", undefined, "You have too many conversations. Please reuse an earlier one.");
+        }
+        const session = await service.openSession(projectRoot, target.agentId, { source: SOURCE, sourceRef: visitor });
+        return this.json(res, 201, { thread: this.threadView(session) });
+    }
+    threadView(session) {
+        return { id: session.id, title: session.title ?? "New chat", updatedAt: session.updatedAt };
+    }
+    ownedSession(target, visitor, threadId) {
+        const found = this.options.service.listSessionsForRef(this.options.projectRoot, target.agentId, SOURCE, visitor, 500).find((session) => session.id === threadId);
+        if (!found)
+            throw new WebChatError("web_chat.unavailable");
+        return found;
+    }
+    /* ---------- sending ---------- */
+    async send(req, res, target, visitor, session) {
+        const { service, chat, projectRoot } = this.options;
+        const slug = target.definition.web_chat.slug ?? "";
+        this.throttle(slug, visitor, req, target, "message");
+        const body = await readJson(req);
+        const text = typeof body.text === "string" ? body.text.trim() : "";
+        if (text.length === 0)
+            throw new WebChatError("web_chat.invalid");
+        if (text.length > target.definition.web_chat.max_message_chars)
+            throw new WebChatError("web_chat.message_too_long");
+        const current = await service.getSession(projectRoot, session.id);
+        if (current.session.status === "running" || current.session.status === "waiting")
+            throw new WebChatError("web_chat.busy");
+        res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-store", "X-Accel-Buffering": "no" });
+        let finished = false;
+        let writes = Promise.resolve();
+        const write = (frame) => {
+            writes = writes.then(() => writeFrame(res, frame));
+        };
+        res.once("close", () => {
+            if (!finished)
+                chat.stop(session.id);
+        });
+        // An operator may need to approve a tool: tell the visitor once per pending approval, never what it is.
+        let announced = null;
+        const watcher = setInterval(() => {
+            try {
+                const pending = service.pendingApprovalFor(projectRoot, session.id);
+                if (pending && pending !== announced) {
+                    announced = pending;
+                    write({ type: "waiting" });
+                }
+            }
+            catch {
+                // a lookup failure must not fail the turn
+            }
+        }, WAIT_POLL_MS);
+        try {
+            const detail = await chat.send({
+                projectRoot,
+                agentId: target.agentId,
+                sessionId: session.id,
+                text,
+                source: SOURCE,
+                onDelta: (delta) => write({ type: "delta", text: delta }),
+            });
+            finished = true;
+            const reply = [...detail.messages].reverse().find((message) => message.role === "assistant");
+            write(reply
+                ? { type: "done", message: { id: reply.id, role: "assistant", text: reply.text, createdAt: reply.createdAt } }
+                : { type: "done", message: null });
+        }
+        catch (error) {
+            finished = true;
+            const failure = toWebChatError(error);
+            if (failure.code === "web_chat.failed")
+                this.options.logError?.(`public web chat turn failed: ${error instanceof Error ? error.message : String(error)}`);
+            write(errorFrame(failure));
+        }
+        finally {
+            clearInterval(watcher);
+            await writes.catch(() => undefined);
+            if (!res.writableEnded && !res.destroyed)
+                res.end();
+        }
+        return true;
+    }
+    /* ---------- plumbing ---------- */
+    async resolve(slug) {
+        const now = this.now();
+        const cached = this.resolved.get(slug);
+        if (cached && now - cached.at < RESOLVE_TTL_MS) {
+            if (!cached.value)
+                throw new WebChatError("web_chat.unavailable");
+            return cached.value;
+        }
+        const value = /^[a-z0-9]{16,32}$/.test(slug) ? await this.options.service.findWebChatAgent(this.options.projectRoot, slug) : null;
+        this.resolved.set(slug, { at: now, value });
+        if (this.resolved.size > 500)
+            this.resolved.clear();
+        if (!value)
+            throw new WebChatError("web_chat.unavailable");
+        return value;
+    }
+    visitorOf(req) {
+        const raw = req.headers["x-visitor-id"];
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        if (!value || !VISITOR_ID.test(value))
+            throw new WebChatError("web_chat.invalid");
+        return value;
+    }
+    /** Messages and new conversations have their own budgets (`kind`); thread creation gets twice the message limit. */
+    throttle(slug, visitor, req, target, kind) {
+        const limit = target.definition.web_chat.rate_limit_per_minute * (kind === "thread" ? 2 : 1);
+        const now = this.now();
+        const perVisitor = this.limiter.take(`${kind}:v:${slug}:${visitor}`, limit, now);
+        if (!perVisitor.ok)
+            throw new WebChatError("web_chat.rate_limited", perVisitor.retryAfterSec);
+        const address = req.socket.remoteAddress ?? "unknown";
+        const perAddress = this.limiter.take(`${kind}:ip:${slug}:${address}`, limit * 3, now);
+        if (!perAddress.ok)
+            throw new WebChatError("web_chat.rate_limited", perAddress.retryAfterSec);
+    }
+    applyCors(req, res) {
+        const origin = req.headers.origin;
+        res.setHeader("Vary", "Origin");
+        res.setHeader("Cache-Control", "no-store");
+        if (!origin)
+            return;
+        // `Origin: null` (sandboxed frames, file pages) and malformed values are not same-origin and get no CORS headers.
+        let sameOrigin = false;
+        try {
+            sameOrigin = req.headers.host !== undefined && new URL(origin).host === req.headers.host;
+        }
+        catch {
+            sameOrigin = false;
+        }
+        if (sameOrigin || (this.options.allowedOrigins ?? []).includes(origin)) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Access-Control-Allow-Headers", "content-type, x-visitor-id");
+            res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+            res.setHeader("Access-Control-Max-Age", "600");
+        }
+    }
+    json(res, status, body) {
+        if (!res.headersSent)
+            res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(body));
+        return true;
+    }
+}
+async function readJson(req) {
+    try {
+        return await readJsonBody(req, MAX_BODY_BYTES);
+    }
+    catch (error) {
+        if (error instanceof BodyError && error.reason === "too_large")
+            throw new WebChatError("web_chat.message_too_long");
+        throw new WebChatError("web_chat.invalid");
+    }
+}

package/dist/agents/webChat/rateLimit.d.ts

@@ -0,0 +1,15 @@
+/** Fixed-size sliding window per key. In memory: a Host restart forgives everyone, which is fine for abuse control. */
+export declare class SlidingWindowLimiter {
+    private readonly windowMs;
+    private readonly hits;
+    private lastPrune;
+    constructor(windowMs?: number);
+    /** Records one hit unless the key is over `limit`; otherwise says how long until a slot frees up. */
+    take(key: string, limit: number, now: number): {
+        ok: true;
+    } | {
+        ok: false;
+        retryAfterSec: number;
+    };
+    private prune;
+}

package/dist/agents/webChat/rateLimit.js

@@ -0,0 +1,33 @@
+/** Fixed-size sliding window per key. In memory: a Host restart forgives everyone, which is fine for abuse control. */
+export class SlidingWindowLimiter {
+    windowMs;
+    hits = new Map();
+    lastPrune = 0;
+    constructor(windowMs = 60_000) {
+        this.windowMs = windowMs;
+    }
+    /** Records one hit unless the key is over `limit`; otherwise says how long until a slot frees up. */
+    take(key, limit, now) {
+        this.prune(now);
+        const recent = (this.hits.get(key) ?? []).filter((at) => now - at < this.windowMs);
+        if (recent.length >= limit) {
+            this.hits.set(key, recent);
+            return { ok: false, retryAfterSec: Math.max(1, Math.ceil((recent[0] + this.windowMs - now) / 1000)) };
+        }
+        recent.push(now);
+        this.hits.set(key, recent);
+        return { ok: true };
+    }
+    prune(now) {
+        if (now - this.lastPrune < this.windowMs)
+            return;
+        this.lastPrune = now;
+        for (const [key, list] of this.hits) {
+            const recent = list.filter((at) => now - at < this.windowMs);
+            if (recent.length === 0)
+                this.hits.delete(key);
+            else
+                this.hits.set(key, recent);
+        }
+    }
+}

package/dist/agents/webChat/slug.d.ts

@@ -0,0 +1,2 @@
+/** A 16-character random link token. The link is the credential, so it comes from the CSPRNG. */
+export declare function newWebChatSlug(): string;

package/dist/agents/webChat/slug.js

@@ -0,0 +1,9 @@
+import { randomInt } from "node:crypto";
+const ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
+/** A 16-character random link token. The link is the credential, so it comes from the CSPRNG. */
+export function newWebChatSlug() {
+    let slug = "";
+    for (let index = 0; index < 16; index += 1)
+        slug += ALPHABET[randomInt(ALPHABET.length)];
+    return slug;
+}