@cosmoops/connect-sdk 0.15.0 → 0.16.1

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

@@ -5,7 +5,9 @@ import { Button, Input, Label, TextField } from "@heroui/react";
 import { Brain, ChevronDown, Send, Sparkles, Square, X } from "lucide-react";
 import { Streamdown } from "streamdown";
 import { useConnect } from "../provider.js";
-import { AiChart, AiDetails, AiMetrics, AiSources, AiSteps, AiTable, AiTimeline } from "./ai-widgets.js";
+import { useActivePath } from "../use-active-path.js";
+import { matchConnectScreen } from "./ai-screens.js";
+import { AiActions, AiChart, AiDetails, AiMetrics, AiSources, AiSteps, AiTable, AiTimeline } from "./ai-widgets.js";
 /**
  * The panel's open width. The *inner* pane always carries it, so the content
  * keeps its layout while the outer shell's width animates to zero around it.
@@ -63,7 +65,7 @@ function ThinkingDisclosure({ text, isStreaming }) {
  */
 const isArray = (value) => Array.isArray(value) && value.length > 0;
 const field = (input, key) => typeof input === "object" && input !== null ? input[key] : undefined;
-function renderTool(name, input, renderMarkdown) {
+function renderTool(name, input, renderMarkdown, screens, renderLink) {
     switch (name) {
         case "showTable":
             return isArray(field(input, "columns")) && Array.isArray(field(input, "rows")) ? (_jsx(AiTable, { ...input })) : null;
@@ -79,6 +81,12 @@ function renderTool(name, input, renderMarkdown) {
             return isArray(field(input, "steps")) ? (_jsx(AiSteps, { ...input, renderDetail: renderMarkdown })) : null;
         case "showSources":
             return isArray(field(input, "sources")) ? _jsx(AiSources, { ...input }) : null;
+        case "showActions":
+            // Every href is checked against the declared screens before anything is
+            // drawn - see `AiActions`. With none declared, nothing resolves and the
+            // tool renders nothing, which is the correct outcome rather than a
+            // collection of dead links.
+            return isArray(field(input, "actions")) ? (_jsx(AiActions, { ...input, screens: screens, renderLink: renderLink })) : null;
         default:
             return null;
     }
@@ -220,7 +228,7 @@ function appendText(blocks, text) {
  * Neither is something the browser can discover, so both surface as a message
  * in the panel rather than as a hidden button.
  */
-export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placeholder = "Ask a question...", hint = "Ask a question about your workspace - answers are grounded in what your team has indexed.", defaultOpen = false, markdownPlugins, }) {
+export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placeholder = "Ask a question...", hint = "Ask a question about your workspace - answers are grounded in what your team has indexed.", defaultOpen = false, markdownPlugins, screens = [], activePath, renderLink, }) {
     const { session, isLoading, streamResource } = useConnect();
     const [isOpen, setIsOpen] = useState(defaultOpen);
     const [turns, setTurns] = useState([]);
@@ -239,6 +247,16 @@ export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", pl
     // A conversation left mid-stream should stop costing tokens the moment the
     // panel goes away.
     useEffect(() => () => abortRef.current?.abort(), []);
+    /**
+     * The declared screen the user is on, if any.
+     *
+     * Drives the opening chips here and travels with each message so the answer
+     * is written from where they are standing. `null` whenever nothing matches -
+     * an application need only describe the screens it wants the assistant to
+     * know about.
+     */
+    const resolvedPath = useActivePath(activePath);
+    const currentScreen = useMemo(() => (resolvedPath ? matchConnectScreen(screens, resolvedPath) : null), [screens, resolvedPath]);
     const renderMarkdown = useCallback((text, isStreaming = false) => (_jsx(Streamdown, { className: "connect-ai-body", mode: isStreaming ? "streaming" : "static", isAnimating: isStreaming, animated: ANIMATED, caret: isStreaming ? "block" : undefined, plugins: markdownPlugins, 
         // Retrieved documents cite real URLs; an interstitial on every one of
         // them turns a citation into a chore. The renderer still sanitises the
@@ -283,7 +301,15 @@ export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", pl
         try {
             // Relative to the provider's own `basePath` - `streamResource` prefixes
             // it, the same way every other bridge call is addressed.
-            const response = await streamResource("/ai/chat", { messages: history }, { signal: controller.signal });
+            const response = await streamResource("/ai/chat", {
+                messages: history,
+                // What the assistant is told about where the user is, and what your
+                // application's screens are. Both are prose: Connect uses them to
+                // write a better answer and to validate action links, never to
+                // decide what anyone may do. See `ConnectScreen`.
+                ...(resolvedPath ? { screenContext: { pathname: resolvedPath } } : {}),
+                ...(screens.length > 0 ? { screens } : {}),
+            }, { signal: controller.signal });
             // The assistant's turn is appended only once the stream is live, so a
             // failed request leaves an error under the question rather than an
             // empty bubble that never fills.
@@ -330,7 +356,7 @@ export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", pl
                 // The user's own turn is shown as they typed it - running a
                 // question that happens to start with `#` through the markdown
                 // renderer would turn it into a heading.
-                _jsx("div", { children: turn.role === "user" ? (_jsx("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.input === null ? (_jsx(ToolSkeleton, {}, block.id)) : (_jsx("div", { children: renderTool(block.name, block.input, renderMarkdown) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && _jsx(ThinkingShimmer, {})] }, turn.id));
+                _jsx("div", { children: turn.role === "user" ? (_jsx("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.input === null ? (_jsx(ToolSkeleton, {}, block.id)) : (_jsx("div", { children: renderTool(block.name, block.input, renderMarkdown, screens, renderLink) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && _jsx(ThinkingShimmer, {})] }, turn.id));
     }), [turns, isAnswering, lastTurn?.id, assistantName, renderMarkdown]);
     // Signed out there is no workspace to ground an answer in, and the bridge
     // would answer 401 - so there is nothing to offer, not even a button.
@@ -344,7 +370,7 @@ export function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", pl
         setInput("");
         void send(text);
     };
-    return (_jsxs(_Fragment, { children: [!isOpen && (_jsx(Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: _jsx(Sparkles, { className: "size-5" }) })), _jsx("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), _jsx("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: _jsxs("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [_jsx(Sparkles, { className: "size-4 shrink-0 text-accent" }), _jsx("span", { className: "flex-1 text-sm font-semibold", children: title }), _jsx(Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: _jsx(X, { className: "size-4" }) })] }), _jsxs("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && _jsx("p", { className: "text-sm text-muted", children: hint }), rendered, isBusy && lastTurn?.role === "user" && (_jsxs("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [_jsx("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), _jsx(ThinkingShimmer, {})] })), error && _jsx("p", { className: "text-xs text-danger", children: error }), _jsx("div", { ref: bottomRef })] }), _jsxs("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [_jsxs(TextField, { variant: "secondary", className: "flex-1", children: [_jsx(Label, { className: "sr-only", children: placeholder }), _jsx(Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? (_jsx(Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: _jsx(Square, { className: "size-3.5" }) })) : (_jsx(Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: _jsx(Send, { className: "size-3.5" }) }))] })] }) })] }));
+    return (_jsxs(_Fragment, { children: [!isOpen && (_jsx(Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: _jsx(Sparkles, { className: "size-5" }) })), _jsx("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), _jsx("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: _jsxs("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [_jsx(Sparkles, { className: "size-4 shrink-0 text-accent" }), _jsx("span", { className: "flex-1 text-sm font-semibold", children: title }), _jsx(Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: _jsx(X, { className: "size-4" }) })] }), _jsxs("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && (_jsxs("div", { className: "space-y-3", children: [_jsx("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? (_jsx("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => (_jsx(Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && (_jsxs("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [_jsx("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), _jsx(ThinkingShimmer, {})] })), error && _jsx("p", { className: "text-xs text-danger", children: error }), _jsx("div", { ref: bottomRef })] }), _jsxs("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [_jsxs(TextField, { variant: "secondary", className: "flex-1", children: [_jsx(Label, { className: "sr-only", children: placeholder }), _jsx(Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? (_jsx(Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: _jsx(Square, { className: "size-3.5" }) })) : (_jsx(Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: _jsx(Send, { className: "size-3.5" }) }))] })] }) })] }));
 }
 /** Hoisted for the same reference-equality reason as `ANIMATED` - Streamdown compares it by identity. */
 const LINK_SAFETY = { enabled: false };

package/dist/esm/client/index.js

@@ -56,6 +56,7 @@ export { useActivePath } from "./use-active-path.js";
 // same longest-prefix rule the sidebar highlights with, so a breadcrumb or a
 // page title derived from it cannot disagree with the rail.
 export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, filterNavForAudience, } from "./components/nav.js";
+export { matchConnectScreen, isLinkableConnectScreen, } from "./components/ai-screens.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 // `AppShell askAi` mounts this; exported for an app that wants the panel
 // without the frame, or wants it somewhere other than the shell's flex row

package/dist/esm/index.js

@@ -10,7 +10,10 @@
  *   Holds the API key. Never import this from browser code.
  * - `@cosmoops/connect-sdk/client` - React components and hooks. Talks to your
  *   own origin only.
+ * - `@cosmoops/connect-sdk/mcp` - your store's declaration, derived into MCP
+ *   tools. Holds the API key; never import this from browser code.
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
 export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";
+export { describeQueryRejection, storeIndexCovers } from "./store-schema.js";

package/dist/esm/mcp/index.js

@@ -0,0 +1,85 @@
+/**
+ * `@cosmoops/connect-sdk/mcp` - your application's store, as an MCP server.
+ *
+ * Server-only: every call goes out through `ConnectClient`, which holds the API
+ * key. The `browser` export condition resolves this entry to a stub, so an
+ * import from client code fails the build rather than shipping the key.
+ *
+ * ## Zero dependencies, on purpose
+ *
+ * This entry does not import `@modelcontextprotocol/sdk`, and the package takes
+ * no dependency on it. `listTools()` and `callTool()` answer in the shapes the
+ * MCP protocol defines, so wiring them to the official server is four lines and
+ * a transport you choose:
+ *
+ * ```ts
+ * const toolset = createStoreToolset({
+ *   collections: STORE_SCHEMA,
+ *   data: connect.data,
+ *   workspaceId: session.workspaceId,
+ *   asUser: session.sessionToken,
+ * })
+ *
+ * server.setRequestHandler(ListToolsRequestSchema, () => toolset.listTools())
+ * server.setRequestHandler(CallToolRequestSchema, (request) =>
+ *   toolset.callTool(request.params.name, request.params.arguments ?? {}),
+ * )
+ * ```
+ *
+ * The alternative - depending on the MCP SDK so this file could return an
+ * `McpServer` - would put a version of it in every install of this package,
+ * including the ones that never touch MCP, and pin partners to whichever
+ * version shipped here. The protocol shapes are stable and small; the coupling
+ * would not be.
+ *
+ * ## One toolset per session
+ *
+ * `asUser` is an end user's Connect session token, and Connect checks each
+ * collection's declared permission against that member's live roles. A toolset
+ * is therefore scoped to one signed-in user - build it per request from
+ * `getConnectSession()`, or pass a function for `asUser` if the surrounding
+ * server outlives a session.
+ */
+export { deriveStoreTools } from "./tools.js";
+import { deriveStoreTools } from "./tools.js";
+/**
+ * A refusal is a result, not a thrown error.
+ *
+ * MCP draws that distinction deliberately: a protocol error is a fault the
+ * model cannot act on, while `isError: true` is a tool result the model reads
+ * and can respond to. An unservable query and a permission Connect refused are
+ * both things a model should see and adapt to - naming a field it may not
+ * filter on, or telling the user it cannot reach that data - so they come back
+ * as content rather than as a transport failure.
+ */
+function asResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+export function createStoreToolset(options) {
+    const tools = deriveStoreTools(options);
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    return {
+        tools,
+        listTools: () => ({
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
+            })),
+        }),
+        async callTool(name, args) {
+            const tool = byName.get(name);
+            if (!tool) {
+                return asResult(`No such tool: "${name}". Available: ${[...byName.keys()].join(", ")}.`, true);
+            }
+            try {
+                return asResult(JSON.stringify(await tool.execute(args), null, 2));
+            }
+            catch (error) {
+                return asResult(error instanceof Error ? error.message : String(error), true);
+            }
+        },
+    };
+}

package/dist/esm/mcp/tools.js

@@ -0,0 +1,366 @@
+import { storeIndexSignature } from "../store.js";
+import { describeQueryRejection } from "../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) => `  - ${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 = 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 = 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. */
+export 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/esm/server/client.js

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

package/dist/esm/server/handler.js

@@ -331,6 +331,13 @@ export 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/esm/server/resources/ai.js

@@ -27,7 +27,14 @@ export 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: actingAs(input.asUser),
             raw: true,
             signal: options.signal,