@vendoai/vendo 0.4.0

package/dist/wire/box.js

@@ -0,0 +1,268 @@
+import { VendoError } from "@vendoai/core";
+import { json, prefixRoute, route, string } from "./shared.js";
+/** execution-v2 skin contract (Lane C) — the two wire surfaces on the boundary
+    of the box:
+    1. the fn PROXY (`POST /apps/:appId/fn/:name`): the authenticated end-user
+       route that wakes the app's machine through the apps runtime's box door
+       and forwards ONE request to the box's `POST /fn/<name>`, relaying
+       status/body. The tree side of the contract.
+    2. the CALLBACK surface (`/box/...`): plain HTTP, authenticated by the
+       per-app bearer minted at provision (createAppTokens), curl-able from any
+       language inside the box — durable rows over the app-scoped store, and
+       host tools through the SAME guard-bound registry chat uses (approvals
+       and audit intact; a pending approval relays as its pending outcome,
+       never bypasses). The box side of the contract. The box never holds host
+       credentials — this surface is its single authority path. */
+/** The fn-name half of core's 01 §8 grammar (mirrored in manifest.ts). */
+const FN_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+/** Wire-side ceiling on one fn round-trip. The box is a wake-in-a-second
+    sandbox answering a function call, not a batch job; a slower answer should
+    time out loudly at the tree side rather than hold the host request open. */
+const FN_TIMEOUT_MS = 30_000;
+const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const COLLECTION_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Matches the app-data record ceiling (06-apps §6). */
+const ROW_MAX_BYTES = 256 * 1024;
+const decoder = new TextDecoder();
+const TIMED_OUT = Symbol("vendo-box-timeout");
+async function withTimeout(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(TIMED_OUT), ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const fnProxyRoutes = [
+    route("POST", "/apps/:appId/fn/:name", async ({ request, params, deps, context }) => {
+        const appId = string(params["appId"], "app id");
+        const name = params["name"] ?? "";
+        if (!FN_NAME_PATTERN.test(name)) {
+            throw new VendoError("validation", "fn name must match [A-Za-z_][A-Za-z0-9_-]{0,63}");
+        }
+        const ctx = await context("app");
+        // Principal scoping BEFORE any machine work: the same owner-scoped get
+        // every /apps route rides; a non-owner sees the app's absence, not a box.
+        if (await deps.apps.get(appId, ctx) === null) {
+            throw new VendoError("not-found", `app not found: ${appId}`);
+        }
+        const body = new Uint8Array(await request.arrayBuffer());
+        const contentType = request.headers.get("content-type");
+        // Forward ONLY the payload: no cookies, no authorization, no host headers
+        // cross the skin. The box's authority is its own app token, nothing more.
+        const work = deps.apps.box.request(appId, {
+            method: "POST",
+            path: `/fn/${name}`,
+            ...(contentType === null ? {} : { headers: { "content-type": contentType } }),
+            ...(body.byteLength === 0 ? {} : { body }),
+        }, ctx);
+        const answer = await withTimeout(work, FN_TIMEOUT_MS);
+        if (answer === TIMED_OUT) {
+            // The box keeps working; only this wire request gives up. Swallow the
+            // eventual settle so a late failure never surfaces as unhandled.
+            work.catch(() => undefined);
+            return json({ error: { code: "timeout", message: `fn ${name} did not answer within ${FN_TIMEOUT_MS}ms` } }, 504);
+        }
+        // Relay status/body; of the box's headers only content-type crosses back
+        // (no set-cookie or friends smuggled onto the host origin).
+        const relayType = Object.entries(answer.headers)
+            .find(([header]) => header.toLowerCase() === "content-type")?.[1];
+        return new Response(answer.body.byteLength === 0 ? null : answer.body, {
+            status: answer.status,
+            ...(relayType === undefined ? {} : { headers: { "content-type": relayType } }),
+        });
+    }),
+];
+function bearerToken(request) {
+    const match = /^Bearer\s+(.+)$/i.exec(request.headers.get("authorization") ?? "");
+    return match?.[1] ?? null;
+}
+function requireJson(request) {
+    const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (contentType !== "application/json") {
+        throw new VendoError("validation", "content-type must be application/json");
+    }
+}
+async function readBoundedJson(request, maxBytes) {
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    if (bytes.byteLength > maxBytes) {
+        throw new VendoError("validation", "request body exceeds size limit");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decoder.decode(bytes));
+    }
+    catch {
+        throw new VendoError("validation", "request body must be valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new VendoError("validation", "request body must be an object");
+    }
+    return parsed;
+}
+/** The list query the rows surface accepts (mirrors the v1 proxy dialect). */
+function rowsQuery(url) {
+    const refs = {};
+    let limit;
+    let cursor;
+    for (const [key, value] of url.searchParams) {
+        if (key.startsWith("refs.")) {
+            const ref = key.slice("refs.".length);
+            if (ref === "" || value === "") {
+                throw new VendoError("validation", "ref filters require non-empty keys and values");
+            }
+            refs[ref] = value;
+            continue;
+        }
+        if (key === "limit") {
+            if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+                throw new VendoError("validation", "limit must be a positive integer");
+            }
+            limit = Number(value);
+            continue;
+        }
+        if (key === "cursor") {
+            if (value === "")
+                throw new VendoError("validation", "cursor must be a non-empty string");
+            cursor = value;
+            continue;
+        }
+        throw new VendoError("validation", `unknown list query parameter: ${key}`);
+    }
+    return {
+        ...(Object.keys(refs).length === 0 ? {} : { refs }),
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor === undefined ? {} : { cursor }),
+    };
+}
+async function handleRows(wire, appId) {
+    const { request, url, segments, deps } = wire;
+    const collection = segments[2];
+    if (collection === undefined || !COLLECTION_PATTERN.test(collection)) {
+        throw new VendoError("validation", "rows collection must match [A-Za-z0-9_-]{1,64}");
+    }
+    // The app-scoped store namespace: the box: infix keeps box rows apart from
+    // the host-declared v1 storage collections sharing the app:<id> prefix.
+    const records = deps.store.records(`app:${appId}:box:${collection}`);
+    // Lane E redaction guard — nothing a box writes or reads through this door
+    // may carry a known secret value into a store row or a response body.
+    const scrub = (value) => deps.apps.box.redact(appId, value);
+    if (segments.length === 3) {
+        if (request.method !== "GET")
+            return undefined;
+        return json(await scrub(await records.list(rowsQuery(url))));
+    }
+    if (segments.length !== 4)
+        return undefined;
+    const id = segments[3];
+    if (id.length === 0 || id.length > 256) {
+        throw new VendoError("validation", "row id must be 1-256 characters");
+    }
+    if (request.method === "GET") {
+        const record = await records.get(id);
+        if (record === null)
+            throw new VendoError("not-found", `row not found: ${id}`);
+        return json(await scrub(record));
+    }
+    if (request.method === "DELETE") {
+        await records.delete(id);
+        return json({ status: "ok" });
+    }
+    if (request.method === "PUT") {
+        requireJson(request);
+        const body = await readBoundedJson(request, ROW_MAX_BYTES);
+        const unexpected = Object.keys(body).find((key) => key !== "data" && key !== "refs");
+        if (unexpected !== undefined) {
+            throw new VendoError("validation", `unexpected row property: ${unexpected}`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(body, "data")) {
+            throw new VendoError("validation", "row body must contain data");
+        }
+        if (body["refs"] !== undefined) {
+            const refs = body["refs"];
+            if (typeof refs !== "object" || refs === null || Array.isArray(refs)
+                || Object.values(refs).some((value) => typeof value !== "string" || value === "")) {
+                throw new VendoError("validation", "row refs must be an object of non-empty strings");
+            }
+        }
+        // Scrub BEFORE persisting: a secret value must never land in a store row,
+        // even when the box itself sent it.
+        return json(await records.put(await scrub({
+            id,
+            data: body["data"],
+            ...(body["refs"] === undefined ? {} : { refs: body["refs"] }),
+        })));
+    }
+    return undefined;
+}
+async function handleTools(wire, ctx) {
+    const { request, segments, deps } = wire;
+    if (request.method !== "POST" || segments.length !== 3)
+        return undefined;
+    const name = segments[2];
+    if (!TOOL_NAME_PATTERN.test(name)) {
+        throw new VendoError("validation", "tool name must match [a-zA-Z0-9_-]{1,64}");
+    }
+    requireJson(request);
+    const body = await readBoundedJson(request, ROW_MAX_BYTES);
+    const args = body["args"];
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        throw new VendoError("validation", "tool body must be an object containing an args object");
+    }
+    // The SAME guard-bound registry every venue executes through: policy,
+    // grants, approvals, breakers, and audit all see this call. An ask-policy
+    // tool comes back { status: "pending-approval" } — relayed, never bypassed.
+    const outcome = await deps.tools.execute({
+        id: `call_${globalThis.crypto.randomUUID()}`,
+        tool: name,
+        args: args,
+    }, ctx);
+    // Lane E redaction guard — a tool outcome relayed into a response is a
+    // host-side artifact; scrub known secret values before it crosses back.
+    return json(await deps.apps.box.redact(ctx.appId ?? "", outcome));
+}
+export const boxRoutes = [
+    prefixRoute("*", "/box/", async (wire) => {
+        const { request, segments, deps } = wire;
+        // The bearer IS the identity: the per-app token minted at provision, its
+        // hash row the authority (createAppTokens). No cookie, no host principal —
+        // this surface is called from inside the box, in any language, via curl.
+        const presented = bearerToken(request);
+        const identity = presented === null ? null : await deps.appTokens.verify(presented);
+        if (identity === null) {
+            return json({ error: { code: "blocked", message: "invalid app token" } }, 401);
+        }
+        // The box acts AS the app's owner, away, in the app venue — exactly the
+        // authority a tree action carries when the owner isn't looking at it.
+        const ctx = {
+            principal: { kind: "user", subject: identity.subject },
+            venue: "app",
+            presence: "away",
+            sessionId: `box_${identity.appId}`,
+            appId: identity.appId,
+        };
+        // A deleted (or re-owned) app retires its token even before revocation.
+        if (await deps.apps.get(identity.appId, ctx) === null) {
+            return json({ error: { code: "blocked", message: "app token no longer valid" } }, 401);
+        }
+        const area = segments[1];
+        if (area === "rows") {
+            const handled = await handleRows(wire, identity.appId);
+            if (handled !== undefined)
+                return handled;
+        }
+        if (area === "tools") {
+            const handled = await handleTools(wire, ctx);
+            if (handled !== undefined)
+                return handled;
+        }
+        throw new VendoError("not-found", "unknown box route");
+    }),
+];

package/dist/wire/connections.d.ts

@@ -0,0 +1,5 @@
+import { type RouteEntry } from "./shared.js";
+/** 04-actions §3 (block-actions design §B) — per-principal connected
+    accounts. Subject scoping happens HERE: the wire passes exactly the
+    resolved principal; no caller-supplied subject exists on this surface. */
+export declare const connectionRoutes: RouteEntry[];

package/dist/wire/connections.js

@@ -0,0 +1,47 @@
+import { VendoError } from "@vendoai/core";
+import { json, requestJson, route, string } from "./shared.js";
+/** 04-actions §3 (block-actions design §B) — per-principal connected
+    accounts. Subject scoping happens HERE: the wire passes exactly the
+    resolved principal; no caller-supplied subject exists on this surface. */
+export const connectionRoutes = [
+    route("GET", "/connections", async ({ deps, context }) => {
+        const ctx = await context("chat");
+        return json({ connections: await deps.connections.list(ctx.principal) });
+    }),
+    route("POST", "/connections/initiate", async ({ request, deps, context }) => {
+        const body = await requestJson(request);
+        const ctx = await context("chat");
+        return json(await deps.connections.initiate(ctx.principal, {
+            toolkit: string(body["toolkit"], "toolkit"),
+            ...(body["connector"] === undefined ? {} : { connector: string(body["connector"], "connector") }),
+            ...(body["callbackUrl"] === undefined ? {} : { callbackUrl: string(body["callbackUrl"], "callbackUrl") }),
+        }));
+    }),
+    // The connect dock's auto catalog. Host-level rows, but the principal still
+    // resolves first so this surface authenticates exactly like its siblings.
+    // Must precede /connections/:id, which would otherwise swallow "catalog".
+    route("GET", "/connections/catalog", async ({ deps, context }) => {
+        await context("chat");
+        // Optional-capability guard: a pre-catalog custom adapter (plain JS, or
+        // compiled before the interface grew) advertises nothing rather than 500s.
+        return json({ available: await deps.connections.catalog?.() ?? [] });
+    }),
+    // Grouped like the old if-chain arm: ANY method resolves context first, and
+    // an unhandled method falls through to the table's not-found.
+    route("*", "/connections/:id", async ({ request, url, deps, context, params }) => {
+        const connectionId = string(params["id"], "connection id");
+        const connector = url.searchParams.get("connector") ?? "composio";
+        const ctx = await context("chat");
+        if (request.method === "GET") {
+            const connection = await deps.connections.status(ctx.principal, connector, connectionId);
+            if (connection === null)
+                throw new VendoError("not-found", `connection not found: ${connectionId}`);
+            return json(connection);
+        }
+        if (request.method === "DELETE") {
+            await deps.connections.disconnect(ctx.principal, connector, connectionId);
+            return json({});
+        }
+        return undefined;
+    }),
+];

package/dist/wire/context.d.ts

@@ -0,0 +1,22 @@
+import { type RunContext } from "@vendoai/core";
+import { type WireDeps } from "./shared.js";
+/** Append the minted Set-Cookie to the response. Stream/SSE responses carry
+    immutable headers, so re-wrap via `new Response(body, response)` (copies
+    status/statusText/headers into a fresh mutable Headers) before appending. */
+export declare function withAnonCookie(response: Response, setCookie: string | undefined): Response;
+/** Per-request anonymous-session state. The wire handler closure is shared
+    across requests, so this MUST be minted per-invocation — a shared one would
+    leak one visitor's session to the next. INVARIANT: one request resolves to
+    at most ONE anonymous id — `id` caches the first resolution so a route that
+    resolves context twice on a cookie-less request can never mint a second id
+    (which would silently split one request across two subjects and overwrite
+    the Set-Cookie). */
+export interface AnonSession {
+    id?: string;
+    setCookie?: string;
+}
+/** The one context-resolution pass every route shares (kill-list B4): resolve
+    the host principal (or mint/read the per-client anonymous session), enforce
+    the resolver invariants, run the anonymous→signed-in merge, and touch the
+    ephemeral session row. Returned resolver is called per route with a venue. */
+export declare function createContextResolver(deps: WireDeps, anon: AnonSession): (req: Request, venue: RunContext["venue"]) => Promise<RunContext>;

package/dist/wire/context.js

@@ -0,0 +1,190 @@
+import { VendoError, isReservedSubject, principalSchema, } from "@vendoai/core";
+import { BASE_PATH, hex } from "./shared.js";
+/** The anonymous-session machinery + the one shared per-request context
+    resolution pass (kill-list B4): opaque anon cookie mint/read/clear, the
+    anonymous→signed-in merge, and RunContext assembly. Every wire area
+    resolves context through createContextResolver below. */
+function requestHeaders(request) {
+    return Object.fromEntries(request.headers.entries());
+}
+function randomId() {
+    const raw = new Uint8Array(16); // 128-bit session id
+    globalThis.crypto.getRandomValues(raw);
+    return hex(raw);
+}
+function ephemeralPrincipal(subject) {
+    return { kind: "user", subject, ephemeral: true };
+}
+/** 00 overview ("no host principal resolver → an ephemeral session-scoped
+    principal"), 01-core §2, 02-store §4. When `principal(req)` returns null the
+    visitor is anonymous, and each CLIENT gets its OWN ephemeral principal —
+    carried by an opaque httpOnly cookie (a random 128-bit session id) so two
+    anonymous visitors never share threads, grants, approvals, or apps. The
+    cookie is just a pointer: the session's `vendo_sessions` row and its
+    ordinary disk rows are the authority (02-store §4, kill-list B3), so it
+    carries no signature — an invented id names its own empty session. */
+const ANON_COOKIE = "vendo_anon_session";
+/** Secure requests use the `__Host-` prefix against session fixation (cookie
+    tossing): a sibling subdomain could otherwise plant an attacker's own
+    session cookie via `Domain=` and read everything the victim's anonymous
+    session then accrues — browsers refuse `__Host-*` cookies that set Domain or
+    arrive from another host. `__Host-` REQUIRES Secure + Path=/ + no Domain. */
+const ANON_COOKIE_SECURE = `__Host-${ANON_COOKIE}`;
+function anonCookieName(secure) {
+    return secure ? ANON_COOKIE_SECURE : ANON_COOKIE;
+}
+/** Whether a request counts as secure for cookie purposes: its own URL is
+    https, OR the operator-set VENDO_BASE_URL (the TRUSTED origin channel —
+    never x-forwarded-*) is https — i.e. TLS terminates at a proxy and the
+    request reaches this process as http. */
+function secureRequest(url, trustedBaseIsHttps) {
+    return url.protocol === "https:" || trustedBaseIsHttps;
+}
+function readCookie(header, name) {
+    if (header === null)
+        return null;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return null;
+}
+/** The shape of the opaque pointer we mint: 128-bit lowercase hex (randomId). */
+const ANON_ID_PATTERN = /^[0-9a-f]{32}$/;
+/** Read the anonymous-session pointer from the Cookie header; return the id
+    when it is a well-formed 128-bit hex pointer, else null (absent or
+    malformed → the caller mints a fresh session). There is nothing to verify
+    beyond shape: the session's `vendo_sessions` row is the authority, so an
+    invented id merely names its own EMPTY session — guessing a live one is a
+    2^128 search (kill-list B3; ids survive restarts and cross instances with
+    the disk rows). Looks up the name matching the CURRENT request's secure
+    determination — a client switching protocols just gets a fresh ephemeral
+    session. */
+function readAnonCookie(cookieHeader, secure) {
+    const raw = readCookie(cookieHeader, anonCookieName(secure));
+    return raw !== null && ANON_ID_PATTERN.test(raw) ? raw : null;
+}
+/** The Set-Cookie for a freshly minted anonymous session. Secure requests get
+    the fixation-proof `__Host-` form (Secure + Path=/, per the prefix rules);
+    insecure (localhost http dev) keeps the plain name scoped to the wire base. */
+function buildAnonCookie(id, secure) {
+    return secure
+        ? `${ANON_COOKIE_SECURE}=${id}; Path=/; HttpOnly; SameSite=Lax; Secure`
+        : `${ANON_COOKIE}=${id}; Path=${BASE_PATH}; HttpOnly; SameSite=Lax`;
+}
+/** The Set-Cookie that CLEARS the anonymous session (block-actions design §C:
+    the first authenticated request carrying a valid anon cookie merges the
+    session's data and retires the cookie). Same attributes as buildAnonCookie
+    so the browser matches the stored cookie; Max-Age=0 expires it. */
+function clearedAnonCookie(secure) {
+    return secure
+        ? `${ANON_COOKIE_SECURE}=; Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=0`
+        : `${ANON_COOKIE}=; Path=${BASE_PATH}; HttpOnly; SameSite=Lax; Max-Age=0`;
+}
+/** Append the minted Set-Cookie to the response. Stream/SSE responses carry
+    immutable headers, so re-wrap via `new Response(body, response)` (copies
+    status/statusText/headers into a fresh mutable Headers) before appending. */
+export function withAnonCookie(response, setCookie) {
+    if (setCookie === undefined)
+        return response;
+    const rewrapped = new Response(response.body, response);
+    rewrapped.headers.append("set-cookie", setCookie);
+    return rewrapped;
+}
+/** The one context-resolution pass every route shares (kill-list B4): resolve
+    the host principal (or mint/read the per-client anonymous session), enforce
+    the resolver invariants, run the anonymous→signed-in merge, and touch the
+    ephemeral session row. Returned resolver is called per route with a venue. */
+export function createContextResolver(deps, anon) {
+    return async (req, venue) => {
+        const resolved = await deps.principal(req);
+        let principal;
+        // Host-resolved principals keep the process-wide fallback sessionId; only
+        // anonymous requests fall back to their per-client cookie id (below).
+        let sessionId = req.headers.get("x-vendo-session-id") ?? deps.sessionId;
+        if (resolved === null) {
+            const secure = secureRequest(new URL(req.url), deps.trustedBaseIsHttps);
+            let id = anon.id ?? readAnonCookie(req.headers.get("cookie"), secure);
+            if (id === null) {
+                id = randomId();
+                anon.setCookie = buildAnonCookie(id, secure);
+            }
+            anon.id = id;
+            principal = ephemeralPrincipal(`anonymous_${id}`);
+            // 05-guard §2: session/task grants bind to ctx.sessionId. Anonymous
+            // sessions bind per CLIENT (the cookie id), not per PROCESS, so one
+            // visitor's session grant never authorizes another's calls. The explicit
+            // x-vendo-session-id header still wins when the client sets it.
+            if (req.headers.get("x-vendo-session-id") === null)
+                sessionId = `anon_${id}`;
+        }
+        else {
+            const parsed = principalSchema.safeParse(resolved);
+            if (!parsed.success) {
+                throw new VendoError("validation", "principal resolver returned an invalid principal");
+            }
+            // Block-actions design §C: host resolvers mint USER principals only —
+            // org context is derived from membership, never resolved — and the
+            // `vendo:` namespace is reserved for runtime-minted subjects (webhook
+            // trigger principals, org subjects). Both rejections are LOUD: a
+            // resolver colliding with the reserved namespace could otherwise act
+            // as an org or a webhook principal.
+            if (parsed.data.kind !== "user") {
+                throw new VendoError("validation", "principal resolver must mint kind:\"user\" principals; org context is derived from org membership");
+            }
+            if (isReservedSubject(parsed.data.subject)) {
+                throw new VendoError("validation", "principal resolver produced a reserved subject (the vendo: namespace is runtime-minted only)");
+            }
+            principal = parsed.data;
+            // Anonymous→signed-in auto-merge (block-actions design §C): the FIRST
+            // authenticated request still carrying a valid anonymous-session
+            // cookie adopts that session's threads/apps/state into the signed-in
+            // subject (grants, approvals, and connected accounts deliberately do
+            // NOT transfer — consent doesn't change identities), then retires the
+            // cookie. Idempotent: a replay finds nothing to merge and just clears
+            // the cookie again. A merge failure must never take down the request:
+            // the cookie stays, and the next authenticated request retries.
+            if (principal.ephemeral !== true) {
+                const secure = secureRequest(new URL(req.url), deps.trustedBaseIsHttps);
+                const anonId = readAnonCookie(req.headers.get("cookie"), secure);
+                if (anonId !== null) {
+                    try {
+                        const merged = await deps.sessionStore.adopt(`anonymous_${anonId}`, principal.subject);
+                        anon.setCookie = clearedAnonCookie(secure);
+                        if (merged !== null) {
+                            await deps.guard.report({
+                                id: `aud_${globalThis.crypto.randomUUID()}`,
+                                at: new Date().toISOString(),
+                                kind: "principal",
+                                principal,
+                                venue,
+                                presence: "present",
+                                detail: { event: "anon-merge", from: `anonymous_${anonId}`, ...merged },
+                            });
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`[vendo] anonymous-session merge failed; will retry next request: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+        }
+        // 02-store §4 (kill-list B3): anonymous rows are ordinary disk rows;
+        // registering the subject (registration == touch) is what makes the
+        // session sweepable and keeps it alive while the visitor is active. One
+        // touch covers both anonymous and host-resolved ephemeral principals.
+        if (principal.ephemeral === true) {
+            await deps.sessionStore.register(principal.subject, deps.sessions.now());
+        }
+        return {
+            principal,
+            venue,
+            presence: "present",
+            sessionId,
+            requestHeaders: requestHeaders(req),
+        };
+    };
+}

package/dist/wire/doctor.d.ts

@@ -0,0 +1,19 @@
+import type { ExtractedTool } from "@vendoai/actions";
+import { type Principal } from "@vendoai/core";
+import { type RouteEntry } from "./shared.js";
+export declare const DOCTOR_ACT_AS_PRINCIPAL: Principal;
+export declare const DOCTOR_ACT_AS_APP_ID: "app_vendo_doctor";
+export declare const doctorPresentTool: ExtractedTool;
+export declare const doctorActAsTool: ExtractedTool;
+/** Doctor targets a running dev server. The prefix gate keeps its synthetic
+    mint/echo routes out of production entirely (and falls through in
+    development); the echo halves expose no credential material — booleans
+    only.
+
+    `/doctor/base-url` (09-vendo §2 install-dx wave 1.1) is listed BEFORE that
+    gate on purpose: unlike the synthetic credential round-trips, it reports a
+    static composition fact (is VENDO_BASE_URL set?) that reveals no secret
+    material, and it is exactly the environment — production — the gate
+    otherwise silences. Placing it first lets it win the route-table scan in
+    every environment, gate included. */
+export declare const doctorRoutes: RouteEntry[];