@cosmoops/connect-sdk 0.15.0 → 0.16.1

package/dist/cjs/mcp/tools.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveStoreTools = deriveStoreTools;
+const store_js_1 = require("../store.js");
+const store_schema_js_1 = require("../store-schema.js");
+/**
+ * The store, as tools a model can call.
+ *
+ * ## Why a declaration is enough
+ *
+ * `Application.storeSchema` already answers every question a tool definition
+ * asks. It names the collection and says what it holds (`description`), which
+ * fields may be filtered or ordered on (`queryableFields`), which query shapes
+ * the database can actually serve (`indexes`), and whether the collection
+ * refuses everything but a create (`appendOnly`). Writing those tools by hand
+ * means maintaining a second copy of all of it, and the copy is wrong the first
+ * time a filter is added to a screen.
+ *
+ * So they are derived. Adding a queryable field to the declaration and
+ * re-seeding widens the tools on the next boot, with no tool code to touch.
+ *
+ * ## What this is not
+ *
+ * **It is not an authorization boundary.** Connect is. Every call here goes out
+ * with the end user's session token (`asUser`), and Connect resolves it to a
+ * member and checks the collection's declared `readPermission`/`writePermission`
+ * against that member's live roles - so a tool can never reach further than the
+ * person on whose behalf it runs, and a permission revoked in the console is
+ * gone from the next call. The shaping done here - omitting write tools for an
+ * `appendOnly` collection, refusing an unservable query - is there so a model
+ * fails fast and legibly, not because it protects anything. Connect refuses the
+ * same things independently.
+ *
+ * **There is no `scan` tool, deliberately.** `data.scan` reads a collection
+ * across every workspace and, for exactly that reason, takes no `asUser` - a
+ * workspace admin is an admin of their own workspace and not of a partner's
+ * other customers. A toolset that runs on behalf of a signed-in user therefore
+ * has nothing to derive from `crossWorkspace`, and generating a scan tool would
+ * mean running that one call under the application's own key while every tool
+ * beside it ran under the user's. Cross-tenant reads belong in a back-office
+ * surface with its own gate.
+ *
+ * **`kv` collections are skipped.** The key/value store is addressed by
+ * namespace and key rather than queried, so it derives nothing from
+ * `queryableFields` or `indexes` and the tools it wants are a different shape.
+ *
+ * ## Deriving over every collection is usually wrong
+ *
+ * Measured on the two reference applications: club's fifteen collections yield
+ * 45 read tools and 88 with writes on; CRM's seven yield 21 and 40. Those are
+ * whole-catalogue numbers, and a model offered them chooses worse than one
+ * offered a handful - the ceiling is tool-choice accuracy, which degrades well
+ * before a context window fills. Connect's own assistant bounds each turn to
+ * the capabilities the current screen promotes for exactly this reason.
+ *
+ * So `include` is the normal way to call this, not a refinement: name the
+ * collections the surface at hand is about. Nothing here enforces a cap,
+ * because the right number depends on the surface and a silent truncation
+ * would be worse than a large list.
+ */
+/** Connect's own ceilings, mirrored so a tool can describe them before the call. */
+const MAX_QUERY_LIMIT = 200;
+const DEFAULT_QUERY_LIMIT = 50;
+const QUERY_OPERATORS = [
+    "==",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "in",
+    "not-in",
+    "array-contains",
+];
+/**
+ * MCP tool names are `[a-z0-9_-]`; collection names additionally allow capitals.
+ * Lowercasing and folding `-` to `_` is what makes `dues-demands` addressable,
+ * and is also how two collections can collide - which is caught, not resolved,
+ * because silently renaming one would make the tool a model calls depend on
+ * declaration order.
+ */
+function toolBaseName(collection) {
+    return collection.toLowerCase().replace(/-/g, "_");
+}
+/**
+ * How many index shapes are worth spelling out before the listing costs more
+ * than it teaches.
+ *
+ * A real declaration is not a handful. club's ledger declares around forty
+ * shapes, and writing all of them into both the list and aggregate tools was
+ * most of a 79 KB `tools/list` on its own - paid on every turn, for a listing a
+ * model reads poorly anyway. Past this many, the description states the rule
+ * and leaves the specifics to the refusal, which names the exact index a
+ * rejected query needed and costs no round trip to get.
+ */
+const MAX_DESCRIBED_INDEXES = 12;
+/** The servable query shapes, spelled out for the model rather than left to be discovered. */
+function describeIndexes(collection) {
+    if (collection.indexes.length === 0) {
+        return "No composite indexes are declared, so a query may use at most one filter, ordered only by that same field.";
+    }
+    const preamble = "A query using more than one filter, or ordering by a field it does not filter on, must match a declared composite index";
+    if (collection.indexes.length > MAX_DESCRIBED_INDEXES) {
+        return `${preamble}. ${collection.indexes.length} are declared - too many to list here. Issue the query you want: if no index covers it you get back the exact index it would need, before anything is read.`;
+    }
+    const shapes = collection.indexes.map((index) => `  - ${(0, store_js_1.storeIndexSignature)(index.fields)}`).join("\n");
+    return `${preamble}:\n${shapes}`;
+}
+function readDescription(collection, verb) {
+    const head = `${verb} ${collection.name}. ${collection.description}`;
+    // Nothing declared queryable means the collection can only be read whole -
+    // which is the right shape for the one-document-per-key collections (a
+    // settings block, a counter), and saying so beats offering a filter argument
+    // that has no legal value.
+    if (collection.queryableFields.length === 0) {
+        return `${head}\n\nThis collection declares no queryable fields, so it cannot be filtered or ordered - it is read whole.`;
+    }
+    return [head, "", `Queryable fields: ${collection.queryableFields.join(", ")}.`, describeIndexes(collection)].join("\n");
+}
+const filtersSchema = (collection) => ({
+    type: "array",
+    description: "Filters, ANDed together.",
+    items: {
+        type: "object",
+        properties: {
+            field: { type: "string", enum: [...collection.queryableFields] },
+            op: { type: "string", enum: QUERY_OPERATORS },
+            value: {
+                description: "The value to compare against. Dates are ISO-8601 strings; a calendar day is YYYY-MM-DD.",
+            },
+        },
+        required: ["field", "op", "value"],
+        additionalProperties: false,
+    },
+});
+/**
+ * Documents come back with Connect's `_`-prefixed bookkeeping on them, and
+ * every write refuses those fields. Saying so on the write tools is what stops
+ * a model reading a document, editing one field and posting the whole thing
+ * back - which fails, correctly, but wastes a turn learning it.
+ */
+const WRITE_DATA_NOTE = "Fields beginning with `_` are written by Connect and are refused here - strip `_createdAt`, `_updatedAt`, `_createdBy`, `_updatedBy` and `_updateTime` from a document you read before writing it back.";
+function buildReadTools(collection, base, call, data, workspaceId) {
+    return [
+        {
+            name: `${base}_get`,
+            title: `Get one ${collection.name} document`,
+            description: `Read one document from ${collection.name} by id. ${collection.description}`,
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string", description: "The document id." } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: (args) => call((asUser) => data.get({ workspaceId, collection: collection.name, id: String(args.id), asUser })),
+        },
+        {
+            name: `${base}_list`,
+            title: `List ${collection.name}`,
+            description: readDescription(collection, "List documents in"),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ...(collection.queryableFields.length > 0
+                        ? {
+                            filters: filtersSchema(collection),
+                            orderBy: {
+                                type: "object",
+                                properties: {
+                                    field: { type: "string", enum: [...collection.queryableFields] },
+                                    direction: { type: "string", enum: ["asc", "desc"] },
+                                },
+                                required: ["field", "direction"],
+                                additionalProperties: false,
+                            },
+                        }
+                        : {}),
+                    limit: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: MAX_QUERY_LIMIT,
+                        description: `Page size. Defaults to ${DEFAULT_QUERY_LIMIT}, caps at ${MAX_QUERY_LIMIT}.`,
+                    },
+                    cursor: {
+                        type: "string",
+                        description: "The previous page's nextCursor. A null nextCursor is the end of the collection.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: async (args) => {
+                const filters = args.filters ?? [];
+                const orderBy = args.orderBy ?? null;
+                const rejection = (0, store_schema_js_1.describeQueryRejection)(collection, { filters, orderBy });
+                if (rejection)
+                    throw new Error(rejection);
+                return call((asUser) => data.query({
+                    workspaceId,
+                    collection: collection.name,
+                    filters,
+                    orderBy: orderBy ?? undefined,
+                    limit: args.limit,
+                    cursor: args.cursor ?? null,
+                    asUser,
+                }));
+            },
+        },
+        {
+            name: `${base}_aggregate`,
+            title: `Count, sum or average ${collection.name}`,
+            description: [
+                readDescription(collection, "Aggregate"),
+                "",
+                "Counts, sums and averages are computed in the database rather than by reading rows back, so prefer this over listing a collection to add it up. A sum or average over nothing answers null, not 0.",
+            ].join("\n"),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    aggregations: {
+                        type: "array",
+                        minItems: 1,
+                        items: {
+                            type: "object",
+                            properties: {
+                                op: {
+                                    type: "string",
+                                    // `sum` and `avg` need a field, and every field they could
+                                    // name must be queryable - so a collection declaring none can
+                                    // only be counted.
+                                    enum: collection.queryableFields.length > 0 ? ["count", "sum", "avg"] : ["count"],
+                                },
+                                ...(collection.queryableFields.length > 0
+                                    ? {
+                                        field: {
+                                            type: "string",
+                                            enum: [...collection.queryableFields],
+                                            description: "Required for sum and avg; omitted for count, which counts documents.",
+                                        },
+                                    }
+                                    : {}),
+                                alias: { type: "string", description: "What the result is keyed by." },
+                            },
+                            required: ["op", "alias"],
+                            additionalProperties: false,
+                        },
+                    },
+                    ...(collection.queryableFields.length > 0 ? { filters: filtersSchema(collection) } : {}),
+                },
+                required: ["aggregations"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: async (args) => {
+                const filters = args.filters ?? [];
+                // An aggregation has no ordering, so the index it needs is the one its
+                // filters need - the same check `list` makes, minus the sort.
+                const rejection = (0, store_schema_js_1.describeQueryRejection)(collection, { filters, orderBy: null });
+                if (rejection)
+                    throw new Error(rejection);
+                return call((asUser) => data.aggregate({
+                    workspaceId,
+                    collection: collection.name,
+                    aggregations: args.aggregations,
+                    filters,
+                    asUser,
+                }));
+            },
+        },
+    ];
+}
+function buildWriteTools(collection, base, call, data, workspaceId, writes) {
+    if (writes === "none")
+        return [];
+    const tools = [
+        {
+            name: `${base}_create`,
+            title: `Create a ${collection.name} document`,
+            description: `Create a document in ${collection.name}. ${collection.description}\n\n${WRITE_DATA_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    data: { type: "object", description: "The document's fields." },
+                    id: { type: "string", description: "Choose the id, or omit for an allocated one. An existing id is a conflict." },
+                },
+                required: ["data"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+            execute: (args) => call((asUser) => data.create({
+                workspaceId,
+                collection: collection.name,
+                data: args.data,
+                id: args.id,
+                asUser,
+            })),
+        },
+    ];
+    // An append-only collection refuses a merge and a delete for every caller,
+    // this application's own key included, so deriving those tools would offer a
+    // model two calls that can only ever fail.
+    if (writes === "all" && !collection.appendOnly) {
+        tools.push({
+            name: `${base}_update`,
+            title: `Update a ${collection.name} document`,
+            description: `Merge top-level fields into an existing ${collection.name} document. Fields not named are left alone.\n\n${WRITE_DATA_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    data: { type: "object", description: "The fields to merge." },
+                },
+                required: ["id", "data"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+            execute: (args) => call((asUser) => data.update({
+                workspaceId,
+                collection: collection.name,
+                id: String(args.id),
+                data: args.data,
+                asUser,
+            })),
+        }, {
+            name: `${base}_delete`,
+            title: `Delete a ${collection.name} document`,
+            description: `Delete one document from ${collection.name}. Idempotent - deleting a document that is not there succeeds.`,
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+            execute: (args) => call((asUser) => data
+                .delete({ workspaceId, collection: collection.name, id: String(args.id), asUser })
+                .then(() => ({ deleted: String(args.id) }))),
+        });
+    }
+    return tools;
+}
+/** Every tool one declaration yields, in a stable order. */
+function deriveStoreTools(options) {
+    const { collections, data, workspaceId, writes = "none", prefix = "", include } = options;
+    const resolveUser = typeof options.asUser === "function" ? options.asUser : () => options.asUser;
+    const call = async (run) => run(await resolveUser());
+    const wanted = include ? new Set(include) : null;
+    const selected = collections.filter((collection) => collection.kind === "data" && (!wanted || wanted.has(collection.name)));
+    if (wanted) {
+        const declared = new Set(collections.map((collection) => collection.name));
+        const missing = [...wanted].filter((name) => !declared.has(name));
+        if (missing.length > 0) {
+            throw new Error(`No declaration for ${missing.join(", ")}. Declared collections: ${[...declared].join(", ")}.`);
+        }
+    }
+    const byBaseName = new Map();
+    const tools = [];
+    for (const collection of selected) {
+        const base = `${prefix}${toolBaseName(collection.name)}`;
+        const clash = byBaseName.get(base);
+        if (clash) {
+            throw new Error(`"${collection.name}" and "${clash}" both derive the tool prefix "${base}". Rename one, or give one its own toolset with a prefix.`);
+        }
+        byBaseName.set(base, collection.name);
+        tools.push(...buildReadTools(collection, base, call, data, workspaceId), ...buildWriteTools(collection, base, call, data, workspaceId, writes));
+    }
+    return tools;
+}

package/dist/cjs/server/client.js

@@ -142,4 +142,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.14.0";
+exports.SDK_VERSION = "0.16.1";

package/dist/cjs/server/handler.js

@@ -334,6 +334,13 @@ function createConnectHandler(options) {
             const upstream = await client.ai.chat({
                 workspaceId: workspaceId,
                 messages: body.messages,
+                // Forwarded unvalidated on purpose. These are your application's own
+                // description of itself and of where the user is - Connect bounds and
+                // sanitises them on arrival, and uses them only to write the answer and
+                // to validate action links. Nothing here reaches an authorization
+                // decision, so there is nothing for this layer to check more strictly.
+                screenContext: body.screenContext,
+                screens: body.screens,
                 // Connect re-derives the workspace from this token, so the line above
                 // is belt to its braces - the browser cannot reach another tenant's
                 // Context Index even if this route were changed to trust the request.

package/dist/cjs/server/resources/ai.js

@@ -30,7 +30,14 @@ class AiResource {
             // it from the header. Passing a signed-in user's session token makes
             // Connect derive the workspace from *that* rather than from
             // `workspaceId`, which is what the bridge relies on.
-            json: { workspaceId: input.workspaceId, messages: input.messages },
+            json: {
+                workspaceId: input.workspaceId,
+                messages: input.messages,
+                // Omitted entirely when absent, rather than sent as `undefined` - an
+                // application that describes no screens should send no field.
+                ...(input.screens ? { screens: input.screens } : {}),
+                ...(input.screenContext ? { screenContext: input.screenContext } : {}),
+            },
             headers: (0, acting_as_js_1.actingAs)(input.asUser),
             raw: true,
             signal: options.signal,

package/dist/cjs/store-schema.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeIndexCovers = storeIndexCovers;
+exports.describeQueryRejection = describeQueryRejection;
+const store_js_1 = require("./store.js");
+/**
+ * The signature of an index scanned backwards.
+ *
+ * Firestore serves a query from an index in either direction as long as *every*
+ * ordered field is flipped, so `[a asc, b desc]` also answers `[a desc, b asc]`.
+ * Mirrored by Connect's own `indexCovers`; kept in step with it deliberately,
+ * because a check here that is stricter than the server's would refuse queries
+ * that actually work, and a looser one would promise queries that do not.
+ */
+function reversedIndexSignature(fields) {
+    return (0, store_js_1.storeIndexSignature)(fields.map((entry) => entry.direction === "array-contains"
+        ? entry
+        : { field: entry.field, direction: entry.direction === "asc" ? "desc" : "asc" }));
+}
+/** Whether one of `declared` can serve a query needing exactly `required`. */
+function storeIndexCovers(declared, required) {
+    const wanted = (0, store_js_1.storeIndexSignature)(required);
+    const mirrored = reversedIndexSignature(required);
+    return declared.some((index) => {
+        const signature = (0, store_js_1.storeIndexSignature)(index.fields);
+        return signature === wanted || signature === mirrored;
+    });
+}
+/**
+ * Why a collection cannot serve a query, in words a caller can act on - or
+ * `null` when it can.
+ *
+ * Runs the same two rules Connect runs, in the same order: every field must be
+ * declared queryable, and the shape must be inside an automatic single-field
+ * index or covered by a declared composite one. Checking here rather than
+ * letting the call fail is not about saving a round trip - it is so the refusal
+ * can name the index to declare while the caller still has the query in hand.
+ */
+function describeQueryRejection(collection, query) {
+    const filters = query.filters ?? [];
+    const orderBy = query.orderBy ?? null;
+    const queryable = new Set(collection.queryableFields);
+    const undeclared = [
+        ...new Set([...filters.map((filter) => filter.field), ...(orderBy ? [orderBy.field] : [])]),
+    ].filter((field) => !queryable.has(field));
+    if (undeclared.length > 0) {
+        return `"${collection.name}" cannot be filtered or ordered on ${undeclared.join(", ")}. Queryable fields are: ${collection.queryableFields.join(", ")}.`;
+    }
+    let required;
+    try {
+        required = (0, store_js_1.storeIndexFor)({ filters, orderBy });
+    }
+    catch (error) {
+        // Firestore cannot serve the shape at all - two `array-contains`, ranges
+        // over two fields, a range ordered by another field. No index would help,
+        // so the thrown message is the whole answer.
+        return error instanceof Error ? error.message : String(error);
+    }
+    if (!required)
+        return null;
+    if (storeIndexCovers(collection.indexes, required))
+        return null;
+    return `"${collection.name}" has no index for this query. It would need one over ${required
+        .map((entry) => `${entry.field} (${entry.direction})`)
+        .join(", ")}.`;
+}

package/dist/esm/client/components/ai-screens.js

@@ -0,0 +1,69 @@
+/**
+ * Matching a live path against the screens your application declared.
+ *
+ * The same rule Connect uses for its own routes, and it has to be here too
+ * because only this side knows what your app's routes are: a dynamic segment
+ * matches exactly one path segment, and where several patterns fit, the most
+ * *literal* wins - so `/deals/new` resolves to itself rather than to
+ * `/deals/[dealId]` merely because that also fits.
+ *
+ * Plain functions with no React and no imports beyond the type, so the panel,
+ * the action links and any host that wants to reuse the matching can share one
+ * implementation.
+ */
+/** Trims the query string, the hash and any trailing slash. */
+function normalise(path) {
+    const withoutQuery = path.split(/[?#]/)[0] ?? "";
+    return withoutQuery.length > 1 ? withoutQuery.replace(/\/+$/, "") : withoutQuery;
+}
+/**
+ * The declared screen a live path is on, or `null` if none matches.
+ *
+ * `null` is a normal outcome, not an error: an application need only describe
+ * the screens it wants the assistant to know about, and an undescribed one
+ * simply costs the assistant its orientation rather than costing the user an
+ * answer.
+ */
+export function matchConnectScreen(screens, path) {
+    const segments = normalise(path).split("/").filter(Boolean);
+    let best = null;
+    for (const screen of screens) {
+        const pattern = normalise(screen.path).split("/").filter(Boolean);
+        if (pattern.length !== segments.length)
+            continue;
+        let literals = 0;
+        let matches = true;
+        for (let i = 0; i < pattern.length; i++) {
+            const part = pattern[i];
+            if (part.startsWith("[") && part.endsWith("]"))
+                continue;
+            if (part !== segments[i]) {
+                matches = false;
+                break;
+            }
+            literals++;
+        }
+        if (matches && (!best || literals > best.literals))
+            best = { screen, literals };
+    }
+    return best?.screen ?? null;
+}
+/**
+ * Whether an href the model produced may be rendered as a link.
+ *
+ * Same reasoning as Connect's own `showActions` check, and the same conclusion:
+ * an assistant that can emit an arbitrary URL is a redirect the model can be
+ * talked into, and retrieved content shares a context window with its
+ * tool-calling authority. So a link is drawn only when it resolves to a screen
+ * *your application declared* - which makes an external destination structurally
+ * impossible, since no route pattern has a scheme or a host.
+ *
+ * The protocol-relative form is refused separately: `//evil.example.com` has no
+ * scheme for a path matcher to trip over, and would otherwise reach an anchor
+ * as an absolute destination.
+ */
+export function isLinkableConnectScreen(screens, href) {
+    if (!href.startsWith("/") || href.startsWith("//"))
+        return false;
+    return matchConnectScreen(screens, href) !== null;
+}

package/dist/esm/client/components/ai-widgets.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
+import { Fragment, useMemo, useState } from "react";
 import { Button } from "@heroui/react";
 import { ArrowDown, ArrowUp, ChevronsUpDown, Download, ExternalLink, FileText, Minus, TrendingDown, TrendingUp } from "lucide-react";
+import { isLinkableConnectScreen } from "./ai-screens.js";
 import { AI_EMPTY_VALUE, AI_TONE_CHIP, AI_TONE_DOT, aiStatusTone, formatAiValue, isNumericAiFormat, } from "./ai-format.js";
 /**
  * What Ask AI draws.
@@ -221,3 +222,38 @@ export function AiSources({ sources }) {
                     return (_jsx("li", { children: source.uri ? (_jsxs("a", { href: source.uri, target: "_blank", rel: "noopener noreferrer", className: "flex gap-1.5 rounded-sm hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus", children: [label, _jsx(ExternalLink, { className: "mt-0.5 size-3 shrink-0 text-muted", "aria-hidden": true })] })) : (_jsx("span", { className: "flex gap-1.5", children: label })) }, `${source.uri ?? source.title}-${index}`));
                 }) })] }));
 }
+/**
+ * Where to go next, as links into *your* application.
+ *
+ * ## Why links and not navigation
+ *
+ * The obvious version of "the assistant can act" moves the user. It is also the
+ * version that breaks the property the whole design rests on: nothing happens
+ * without a click. Retrieved content shares a context window with the model's
+ * tool-calling authority, so an auto-navigate is a redirect primitive that
+ * content can reach. A link cannot be, and loses nothing - the user was going
+ * to click something anyway.
+ *
+ * ## Why every href is checked against your declared screens
+ *
+ * The model can emit any string. Only your application knows which strings are
+ * real routes, which is why `screens` is a prop rather than something Connect
+ * could supply. A link that does not resolve is *dropped* rather than rendered
+ * broken - the prose around it still stands, so a missing link reads as terse
+ * rather than wrong.
+ *
+ * `renderLink` is how this stays router-agnostic. Given one, a link is your
+ * framework's - a Next `<Link>`, a TanStack `<Link>` - and navigation is a
+ * client transition. Without one it falls back to an anchor, which works
+ * everywhere and costs a document load.
+ */
+export function AiActions({ title, actions, screens, renderLink, }) {
+    const resolved = actions.filter((action) => isLinkableConnectScreen(screens, action.href));
+    if (resolved.length === 0)
+        return null;
+    const className = "group flex items-center gap-2 rounded-lg border border-separator bg-surface px-3 py-2 no-underline transition-colors hover:border-accent";
+    return (_jsxs("div", { className: "my-3", children: [title ? _jsx("p", { className: "mb-1.5 text-xs font-medium text-muted", children: title }) : null, _jsx("div", { className: "flex flex-col gap-1.5", children: resolved.map((action) => {
+                    const body = (_jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-xs font-medium text-foreground", children: action.label }), action.detail ? (_jsx("span", { className: "block truncate text-[11px] text-muted", children: action.detail })) : null] }));
+                    return (_jsx(Fragment, { children: renderLink ? (renderLink({ href: action.href, className, children: body })) : (_jsx("a", { href: action.href, className: className, children: body })) }, action.href));
+                }) })] }));
+}