@xano/sdk 1.0.8 → 1.0.9

package/dist/{workspace-command-KEKL27Y4.js → workspace-command-N4BTEHSW.js}

@@ -4,13 +4,13 @@ import {
 } from "./chunk-R4NOZBOY.js";
 import {
   fetchWorkspaceBundle
-} from "./chunk-ZQ5WZWHF.js";
-import "./chunk-V7KMIEMF.js";
-import "./chunk-PAS5HOG3.js";
+} from "./chunk-XTUYIX5H.js";
+import "./chunk-HVSIS47X.js";
+import "./chunk-GAU2FCT7.js";
 import "./chunk-QTMXJQZN.js";
 import "./chunk-O376UAZS.js";
 import "./chunk-6YOH2L3G.js";
-import "./chunk-XYTVP4WI.js";
+import "./chunk-GHPC52TD.js";
 import {
   confirm
 } from "./chunk-HQPL34O6.js";
@@ -29,38 +29,38 @@ import {
   reachableWorkspaces,
   refuseUnreachableWorkspace,
   unreachableWorkspaceMessage
-} from "./chunk-FHQYXGAY.js";
-import "./chunk-K75BFHQQ.js";
+} from "./chunk-WLFANUXE.js";
+import "./chunk-YVXUYDHC.js";
 import "./chunk-OBJ7FQDX.js";
 import "./chunk-2TFRR6JV.js";
 import {
   resolveOutputTarget,
   secretsPhrase,
   writeExportFile
-} from "./chunk-AS4G2MIE.js";
+} from "./chunk-S5RZYUP2.js";
 import {
   secretsCarriedBy
 } from "./chunk-I53OTC3O.js";
-import "./chunk-JG642U5D.js";
+import "./chunk-HETQSTGG.js";
 import {
   assertBundleFile,
   assertBundleInput,
   assertEntryFile,
   assertValueFiles,
   loadBundleText
-} from "./chunk-ZJCHS7FM.js";
+} from "./chunk-U7XSQXOA.js";
 import "./chunk-XQO4A4Q4.js";
-import "./chunk-M3RLLT4O.js";
-import "./chunk-S3STXOAO.js";
+import "./chunk-Y2LKSXFK.js";
+import "./chunk-SGYDFEXD.js";
 import "./chunk-PBK257CI.js";
-import "./chunk-7UWUEUVJ.js";
+import "./chunk-INAM6KR6.js";
 import "./chunk-7JKNWDYN.js";
-import "./chunk-C2I4GC36.js";
+import "./chunk-5VOGPS5O.js";
 import "./chunk-VJTTTIIB.js";
 import {
   getAccessToken
-} from "./chunk-QE2GNFMP.js";
-import "./chunk-QRKBFXIB.js";
+} from "./chunk-IFCQCM2Q.js";
+import "./chunk-2VWSUG2B.js";
 import "./chunk-5Y5HWQ2P.js";
 import "./chunk-F3IA3YWI.js";
 import "./chunk-LCOCRJ4K.js";
@@ -69,9 +69,9 @@ import "./chunk-YE7MHW45.js";
 import "./chunk-2MNLRIOX.js";
 import "./chunk-PFW7WFAT.js";
 import "./chunk-CJDPSCMX.js";
-import "./chunk-UKJFCEMI.js";
+import "./chunk-NI56XX5Z.js";
 import "./chunk-VD7YTLWL.js";
-import "./chunk-UU7EEREQ.js";
+import "./chunk-CXWCWYX3.js";
 import "./chunk-S42TFTM5.js";
 import "./chunk-ZYJP6BOO.js";
 import "./chunk-QO6BVGS5.js";
@@ -86,9 +86,9 @@ import {
 } from "./chunk-6S263KTM.js";
 import "./chunk-IB6SKACE.js";
 import "./chunk-EUUUMY7J.js";
-import "./chunk-W2BVP27L.js";
-import "./chunk-HKLBDSML.js";
-import "./chunk-RYMGK2K5.js";
+import "./chunk-6IOQRBRX.js";
+import "./chunk-KDS4PDFD.js";
+import "./chunk-5BEK7YKY.js";
 import "./chunk-B3NH5UBI.js";
 import "./chunk-ZFDZKNGG.js";
 import "./chunk-FWD7AL6N.js";
@@ -144,7 +144,7 @@ import {
   writeJson,
   writeTargetPayload
 } from "./chunk-C6KBZH7M.js";
-import "./chunk-F5RPNTN7.js";
+import "./chunk-T3ZVNOJC.js";
 import "./chunk-OHTHG3LL.js";
 import "./chunk-6JAEMMZ7.js";
 import "./chunk-6ZFJEJXZ.js";
@@ -203,7 +203,7 @@ async function runWorkspaceCommand(args) {
     case "reset-tables":
       return runResetTables(args);
     case "branch": {
-      const { runBranchCommand } = await import("./branch-commands-CR3SAHMV.js");
+      const { runBranchCommand } = await import("./branch-commands-Q6E66PMM.js");
       return runBranchCommand(args);
     }
     default:
@@ -232,7 +232,7 @@ async function runDetails(args) {
   const auth = await getAccessToken(args);
   const workspaceId = auth.workspaceId;
   const all = await fetchWorkspaces(auth).catch(async (err) => {
-    const { unansweredRead } = await import("./source-resolve-LNRUITLS.js");
+    const { unansweredRead } = await import("./source-resolve-I55GN6ZC.js");
     throw unansweredRead(err, "read the workspace list", "workspace");
   });
   const match = all.find((w) => w.id === workspaceId);
@@ -292,7 +292,7 @@ async function runExport(args) {
 var EXIT_DIFF_MISMATCH = 2;
 async function runDiff(args) {
   if (args.file === void 0 && args.bundle === void 0) {
-    const { resolveProjectEntry } = await import("./deploy-source-FPNNNNOW.js");
+    const { resolveProjectEntry } = await import("./deploy-source-TD77W4SA.js");
     const entry = resolveProjectEntry(process.cwd());
     if (entry !== void 0) args = { ...args, file: entry };
   }
@@ -305,11 +305,11 @@ async function runDiff(args) {
   try {
     live = await fetchWorkspaceBundle(auth, args.branch);
   } catch (err) {
-    const { unansweredRead } = await import("./source-resolve-LNRUITLS.js");
+    const { unansweredRead } = await import("./source-resolve-I55GN6ZC.js");
     throw unansweredRead(err, "read the workspace to compare", "workspace");
   }
   const { SETTINGS_LABEL } = await import("./live-diff-CGTGOH3S.js");
-  const { codePinnedCanonicals, releaseCanonicalLock } = await import("./release-command-MKNESNGB.js");
+  const { codePinnedCanonicals, releaseCanonicalLock } = await import("./release-command-USZAWVXO.js");
   const pinned = codePinnedCanonicals(local.bundle, releaseCanonicalLock(args), args.file !== void 0);
   const listed = await listBranches(auth, { baseUrl: auth.instance, workspaceId: auth.workspaceId }).catch(
     () => void 0
@@ -317,7 +317,7 @@ async function runDiff(args) {
   const liveLabel = listed?.find((b) => b.live)?.label;
   const comparedLabel = args.branch ?? liveLabel;
   const comparedIsLive = args.branch === void 0 ? true : liveLabel === void 0 ? null : args.branch === liveLabel;
-  const { landingLockPath } = await import("./landing-record-DO3PM7QP.js");
+  const { landingLockPath } = await import("./landing-record-SJ5HG7T5.js");
   const { readSyncBaseline, storedBranchLabel } = await import("./sync-record-U65BCPSP.js");
   const { directedComparison } = await import("./sync-baseline-3CDL4PKT.js");
   const syncLabel = storedBranchLabel(listed, args.branch);
@@ -560,4 +560,4 @@ export {
   EXIT_DIFF_MISMATCH,
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-KEKL27Y4.js.map
+//# sourceMappingURL=workspace-command-N4BTEHSW.js.map

package/dist/{workspace-env-GGEZVZDY.js → workspace-env-O3RK26FR.js}

@@ -14,10 +14,10 @@ import {
   renderWorkspaceEnvFile,
   valueProblem,
   workspaceEnvPathIn
-} from "./chunk-M3RLLT4O.js";
-import "./chunk-W2BVP27L.js";
-import "./chunk-HKLBDSML.js";
-import "./chunk-RYMGK2K5.js";
+} from "./chunk-Y2LKSXFK.js";
+import "./chunk-6IOQRBRX.js";
+import "./chunk-KDS4PDFD.js";
+import "./chunk-5BEK7YKY.js";
 import "./chunk-B3NH5UBI.js";
 import "./chunk-ZFDZKNGG.js";
 import "./chunk-FWD7AL6N.js";
@@ -68,4 +68,4 @@ export {
   valueProblem,
   workspaceEnvPathIn
 };
-//# sourceMappingURL=workspace-env-GGEZVZDY.js.map
+//# sourceMappingURL=workspace-env-O3RK26FR.js.map

package/dist/{xanosdk-import-HYHABD5U.js → xanosdk-import-WPCHIVP6.js}

@@ -13,7 +13,7 @@ import {
   resetXanoSdkImportDetection,
   withDefaultBranchPointer,
   xanosdkImport
-} from "./chunk-FN7E6XGD.js";
+} from "./chunk-3XSTC3TM.js";
 import "./chunk-3DRXWLJ5.js";
 import "./chunk-X4DVXBFY.js";
 import "./chunk-VJTTTIIB.js";
@@ -53,4 +53,4 @@ export {
   withDefaultBranchPointer,
   xanosdkImport
 };
-//# sourceMappingURL=xanosdk-import-HYHABD5U.js.map
+//# sourceMappingURL=xanosdk-import-WPCHIVP6.js.map

package/dist/{xanosdk-project-2T56DRYS.js → xanosdk-project-TEAXYQZW.js}

@@ -3,11 +3,11 @@ import {
   enterProjectRoot,
   isProjectDir,
   projectDirFrom
-} from "./chunk-C2I4GC36.js";
+} from "./chunk-5VOGPS5O.js";
 import "./chunk-EUUUMY7J.js";
-import "./chunk-W2BVP27L.js";
-import "./chunk-HKLBDSML.js";
-import "./chunk-RYMGK2K5.js";
+import "./chunk-6IOQRBRX.js";
+import "./chunk-KDS4PDFD.js";
+import "./chunk-5BEK7YKY.js";
 import "./chunk-B3NH5UBI.js";
 import "./chunk-ZFDZKNGG.js";
 import "./chunk-FWD7AL6N.js";
@@ -39,4 +39,4 @@ export {
   isProjectDir,
   projectDirFrom
 };
-//# sourceMappingURL=xanosdk-project-2T56DRYS.js.map
+//# sourceMappingURL=xanosdk-project-TEAXYQZW.js.map

package/guides/cli.md

@@ -83,7 +83,7 @@ xanosdk test run-all --kind unit            # only one family (unit|workflow; de
 xanosdk test run-all --concurrency 4        # run 4 at once (default: 1); tests share the backend's database, so only when yours don't share state
 xanosdk impersonate                         # open what this project last deployed to in the builder (--guest = read-only; --url-only prints the URL; the URL is a session — treat it as a credential)
 xanosdk impersonate ephemeral:<tenant>      # …or name one: local[:<name>] or tenant:<name> (open your workspace from the Xano dashboard)
-xanosdk deploy ./xano/index.ts --test        # THE RELEASE FLOW, step 1: stand it up and run its tests
+xanosdk deploy ./xano/index.ts --ephemeral --test   # THE RELEASE FLOW, step 1: stand it up on an ephemeral and run its tests (a bare deploy goes to the Xano Engine, which release create cannot cut from)
 xanosdk release create v1                   # …2: cut a release from the ephemeral this project last deployed to (after a local deploy: --from ephemeral)
 xanosdk release create v1 --from ephemeral:e4f2-9ab1 --description "what shipped"   # …from a named source
 xanosdk release create v1 --from workspace --branch staging   # …or from a branch of your workspace (default: what it serves)
@@ -180,14 +180,15 @@ workspace or a tenant, so a bare command cannot reach something real unasked. Wi
 it falls back to the ephemeral recorded under your current credential, then to the engine
 recorded for this directory, and otherwise refuses naming the flag, `xanosdk deploy` and
 `xanosdk deploy --local`.
-`deploy` is the exception: bare, it compiles the project and stands it up on an ephemeral
-unless `--to` or `--local` says otherwise, so it writes that record rather than
-reading it. `generate` and `init --from` need a backend named.
+`deploy` is the exception: bare, it compiles the project and stands it up on the Xano Engine
+on this machine unless `--ephemeral` or `--to` says otherwise, so it writes that record rather
+than reading it. `generate` and `init --from` need a backend named.
 
 A command that cannot serve a backend refuses it, whether you typed it or it came from the
-record, with the reason and the spellings it does take: `publish` refuses a Xano Engine (no
-static host — pass `--to ephemeral`), and so does `release create` (the cut runs on the
-instance — pass `--from ephemeral`). A write to your workspace or a tenant confirms first,
+record, with the reason and the spellings it does take: `release create` refuses a Xano Engine
+(the cut runs on the instance — pass `--from ephemeral`). `publish` is not one of them: it
+reaches a Xano Engine (`publish --to local`, or bare after a local deploy) and puts the build on
+the engine's own static host. A write to your workspace or a tenant confirms first,
 or needs `--yes` off a terminal; an ephemeral or Xano Engine never asks.
 
 ## Bundle key names vs. the names everything else uses

package/guides/deploying.md

@@ -175,7 +175,8 @@ what ran, then `xanosdk promote <release>` lands it there as a new branch, leavi
 untouched until you say otherwise.
 
 **Static host** — `deploy --static <dir>` archives a directory and deploys it to a
-static host after the backend import. The frontend lands **on the ephemeral itself**, so the
+static host after the backend import. The frontend lands **on the environment the backend just
+went to** — the ephemeral itself, or the Xano Engine (see *A frontend on the Xano Engine, and server rendering*) — so the
 backend and the frontend live in one environment. The CLI uploads the archive to
 `/api:meta/workspace/{id}/static_host/default/build` with your ordinary bearer. That route
 auto-creates the `default` host (and only that one: a `--static-host` naming a host the target
@@ -294,7 +295,7 @@ as three environment variables** — the `type: "token"` record above, with no f
 XANO_INSTANCE_URL=https://your-instance.xano.io \
 XANO_WORKSPACE_ID=3 \
 XANO_META_TOKEN=your-meta-api-token \
-  npx xanosdk deploy ./xano/index.ts
+  npx xanosdk deploy ./xano/index.ts --ephemeral
 ```
 
 Nothing is read from or written to disk, and nothing rotates, so the same three secrets keep
@@ -610,8 +611,10 @@ with `--to` (`--seed`, `--prune`, `--dry-run`, …) stay refused alongside it.
 
 ### Deploying locally
 
-`xanosdk deploy --local` deploys to an engine running on this machine instead of an
-ephemeral — no network round-trip per deploy. It needs nothing configured:
+A bare `xanosdk deploy` deploys to an engine running on this machine — no network round-trip
+per deploy. `--local` is that default spelled out, needed only to name an engine:
+`--local=<version|url|path>` runs that one instead of the pinned version. It needs nothing
+configured:
 
 - **The first run** resolves the latest published engine for this machine's platform,
   downloads it, checks it against the sha256 its release recorded, and **pins** that version in
@@ -1019,7 +1022,7 @@ instead, so stdout is never empty. Branch on `code`, not on the message:
 
 A piped stdout gets the document too, without `--json`, so a script reading the pipe never gets
 an empty stdout. The exception is a command whose stdout is the data itself (`export` to stdout,
-`llms`, `completion`, `--help`): a failure appended to it would corrupt it, so those write one
+`completion`, `--help`): a failure appended to it would corrupt it, so those write one
 only under `--json`. A piped `release` or `promote` write prints its operation result (above)
 either way.
 
@@ -1127,7 +1130,7 @@ or on a second destination, nothing for a tenant to be pointed at, and no record
 build *was* beyond the commit you built it from. Prefer the release flow for anything you may
 need to repeat.
 
-The flags that describe the ephemeral a plain deploy refreshes — `--name`, `--expires-hours`,
+The flags that describe the environment a plain deploy replaces — `--name`, `--expires-hours`,
 `--reset`, `--keep-data`, `--test` (with `--kind`/`--concurrency`), `--no-dev-env`,
 `--require-microservices`, `--open` — are refused beside `--to`, before sign-in. `--static`
 publishes beside the merge, but not under `--dry-run`; `--skip-liveness` needs `--static` there.
@@ -1617,10 +1620,10 @@ and `XANO_META_TOKEN`, [above](#signing-in--deploying-in-depth) — no browser,
 nothing that rotates:
 
 ```bash
-XANO_INSTANCE_URL=… XANO_WORKSPACE_ID=… XANO_META_TOKEN=… npx xanosdk deploy ./xano/index.ts
+XANO_INSTANCE_URL=… XANO_WORKSPACE_ID=… XANO_META_TOKEN=… npx xanosdk deploy ./xano/index.ts --ephemeral
 ```
 
 > ⚠️ A deploy without `--keep-data` is a full replace of the target environment, including
-> its table records, before importing. The blast radius is your own disposable ephemeral — but anything
+> its table records, before importing. The blast radius is your own Xano Engine or disposable ephemeral — but anything
 > you only ever created by hand in it (or any data it accumulated) is gone. That's exactly
 > why a real workspace or tenant is reached only by naming it, with `deploy --to`.

package/llms/kinds-agent-mcp.md

@@ -1,14 +1,15 @@
 # Agent and MCP def shapes
 
-> Read when defining an `agent()`, `mcpServer()`, `prompt()` or `resource()`.
+> Read when building an MCP server (tools, prompts, resources) or an `agent()`.
 
+- An MCP server serves THREE primitives, and each reaches the client differently: a `tool()` is an action the MODEL calls (it may write); a `resource()` is read-only context the client APPLICATION lists and attaches by `uri` (reference docs, a schema, one record through a `{variable}` template); a `prompt()` is a message template with arguments the USER picks by name. Context a session opens with is a `resource()`; a workflow a user starts by name is a `prompt()`; data the model must fetch on its own mid-task stays a `tool()`, since a client shows the model only the resources attached to the conversation. Register each kind (`registerTools`/`registerPrompts`/`registerResources`) and list it on the server.
 - `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).
   - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) is the LEGACY way to publish a tool as an MCP resource — author a `resource()` and list it in `resources` instead; `toolMeta` is extra metadata on a tool entry. The two payload fields are per-type and supplying the other one is refused, because the engine stores it against neither. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — per-tool, and the only gate there is. ⚠ It is also what gives the tool a CALLER, on an `agent()` exactly as on an MCP server. `auth()` inside a tool whose entry names no table does NOT return null: the call answers a normal result carrying `{"code":"ERROR_FATAL","message":""}`, so the model reads a successful tool result and reports success while nothing is written. A caller token does not rescue it — the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.
   - `prompts?` / `resources?`: `prompt()` / `resource()` HANDLES (or names), or a `{ prompt, enabled?, auth? }` / `{ resource, enabled?, auth? }` wrapper. `auth` names the auth table and is what gives the stack a caller: a prompt/resource reading `auth()` behind an entry with none answers every `prompts/get` / `resources/read` with `-32603 "Access Denied"` (`export()` warns `toolset.primitive-reads-auth-ungated`). Listing one target twice THROWS; two resources with one `uri` on one server fail `export()` (`mcp.resource-uri-duplicate`). MCP-server only — `agent()` takes tools only.
   - `history?` is the server tier for its tools, prompts AND resources alike; an object's own `history` wins. The workspace tier (`workspaceConfig({ history })`) has `prompt` and `resource` keys, both default on.
   - `oauth?`: per-server sign-in; omit and nothing changes. Union on `mode`; `authTable` (REQUIRED, auth `table()` handle or name) is whose row the signed-in user is — `auth()` on the whole server, `t.auth` in its trigger. Hosted (the platform is the authorization server): `{ mode: "hosted", authTable, loginUrl }` — clients are sent to `loginUrl` (YOUR page, which is also the consent screen) with `mcp_request`; show `s.mcp.oauth.request`, sign the user in, then your endpoint calls `s.mcp.oauth.complete` with their `decision` and the page redirects to the URL it binds. External (your IdP issues tokens): `{ mode: "external", authTable, issuer, column, audience?, audienceAck?, claim?, claimAck?, preset?, allowedClientIds? }` — token `claim` (default `sub`) matched against `column`; `preset` is `auth0|clerk|workos|entra|okta|cognito|generic`. `loginUrl`/`issuer`/`audience` take `env("NAME")` (resolved per environment).
     - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` — users can edit it at most providers). Unknown `mode`/`preset` THROWS; so do the dropped `consent`/`branding`/`trustedClients`.
-- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
+- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order, `content` a string or an MCP content block: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
 - `resource({ name, uri, guid?, description?, docs?, mimeType?, title?, icons?, annotations?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP resource; takes `registerResources`. Clients address it by `uri`, never `name`.
   - `uri`: a literal (`"docs://readme"`, no `input`) or an RFC 6570 LEVEL-1 template (`"orders://{region}/{order_id}"`). It must start with a scheme; each `{variable}` is letters/digits/`_`, one per brace pair, never two adjacent. `input` must be EXACTLY the template's variables, each a single `text`/`int`/`decimal`/`bool`/`enum`/`email`/`uuid` — anything else THROWS. A value that does not convert is refused before the stack runs.
   - `response`: a string is returned as text; non-UTF-8 content (a file, binary) as a base64 blob. `mimeType?` omitted → derived from what the stack returns.

package/llms/object-kinds.md

@@ -4,6 +4,20 @@
 
 Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
 
+### Choosing a kind
+
+Choose by who or what starts the work. Each rule names the kind that fits and the one it gets mistaken for.
+
+- **Logic other code calls** → `defineFunction`, run with `s.function.run`. A `query` is the only kind an HTTP client reaches by verb + path; a `tool` is what an `agent()` or an MCP client calls. Logic serving two callers (an endpoint AND a tool) lives in one function both call.
+- **Work on a timer** → `task` (cron or interval). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every insert/update/delete of the table, whichever stack writes it, so the same side effect placed in one endpoint's stack misses every other write path.
+- **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or API group) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
+- **Related rows on returned rows** → an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` — not a second read plus a loop that stitches rows together.
+- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()`; an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
+- **Pushing to connected clients** → `realtimeServer` → `realtimeChannel` → `realtimeMessage` (the handler for a frame a client sends — the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.
+- **Code the typed surface cannot express** → a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.
+- **Tests** → `tests` on a `query`/`defineFunction`/`middleware` for that one object's input → output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.
+- **Reacting to the platform** → `errorTrigger` (an error signature first seen, regressing, or marked fixed) and `workspaceTrigger` (branch new/merge/live). What one connection to an MCP server, agent, realtime server or channel may see or do → that object's connection trigger.
+
 ⚠ Composing a workspace from independently-authored modules: `register*` takes its defs however they arrive, but `modules.flatMap((m) => m.tables)` does NOT typecheck. `Array.prototype.flatMap` binds its element type to the FIRST element, so every later module's tables are checked against that one table's schema — the error compares two unrelated column names and mentions neither `flatMap` nor the cause. `.concat()` collapses the same way. Two spellings work: pass an array LITERAL (`registerTables([...a.tables, ...b.tables])` — spreads are fine, TypeScript infers the union across every element at once), or annotate the module array with the wide aliases `AnyTableDef` / `AnyQueryDef` / `AnyFunctionDef` / `AnyAddonDef`, exported for exactly the four def types whose generics can collapse this way. Widening the array costs nothing: the typing you need lives on the `table()`/`query()` handle you hold and pass to `s.db.*`, and is never read back off the registered array.
 
 - function: `defineFunction` → `Xano.registerFunctions` → payload `function` — Reusable server-side logic (a custom function) callable from any stack via `s.function.run`.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.8
+# xanosdk v1.0.9
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -43,7 +43,7 @@ plain file read resolves them at the version you have.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
-- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when defining an `agent()`, `mcpServer()`, `prompt()` or `resource()`.
+- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
 - [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item for its AI agents.
 - [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
@@ -498,6 +498,20 @@ Control flow & blocks (each nests a sub-stack; block specials name it `body`):
 
 Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
 
+### Choosing a kind
+
+Choose by who or what starts the work. Each rule names the kind that fits and the one it gets mistaken for.
+
+- **Logic other code calls** → `defineFunction`, run with `s.function.run`. A `query` is the only kind an HTTP client reaches by verb + path; a `tool` is what an `agent()` or an MCP client calls. Logic serving two callers (an endpoint AND a tool) lives in one function both call.
+- **Work on a timer** → `task` (cron or interval). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every insert/update/delete of the table, whichever stack writes it, so the same side effect placed in one endpoint's stack misses every other write path.
+- **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or API group) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
+- **Related rows on returned rows** → an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` — not a second read plus a loop that stitches rows together.
+- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()`; an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
+- **Pushing to connected clients** → `realtimeServer` → `realtimeChannel` → `realtimeMessage` (the handler for a frame a client sends — the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.
+- **Code the typed surface cannot express** → a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.
+- **Tests** → `tests` on a `query`/`defineFunction`/`middleware` for that one object's input → output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.
+- **Reacting to the platform** → `errorTrigger` (an error signature first seen, regressing, or marked fixed) and `workspaceTrigger` (branch new/merge/live). What one connection to an MCP server, agent, realtime server or channel may see or do → that object's connection trigger.
+
 ⚠ Composing a workspace from independently-authored modules: `register*` takes its defs however they arrive, but `modules.flatMap((m) => m.tables)` does NOT typecheck. `Array.prototype.flatMap` binds its element type to the FIRST element, so every later module's tables are checked against that one table's schema — the error compares two unrelated column names and mentions neither `flatMap` nor the cause. `.concat()` collapses the same way. Two spellings work: pass an array LITERAL (`registerTables([...a.tables, ...b.tables])` — spreads are fine, TypeScript infers the union across every element at once), or annotate the module array with the wide aliases `AnyTableDef` / `AnyQueryDef` / `AnyFunctionDef` / `AnyAddonDef`, exported for exactly the four def types whose generics can collapse this way. Widening the array costs nothing: the typing you need lives on the `table()`/`query()` handle you hold and pass to `s.db.*`, and is never read back off the registered array.
 
 - function: `defineFunction` → `Xano.registerFunctions` → payload `function` — Reusable server-side logic (a custom function) callable from any stack via `s.function.run`.
@@ -849,15 +863,16 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 # Agent and MCP def shapes
 
-> Read when defining an `agent()`, `mcpServer()`, `prompt()` or `resource()`.
+> Read when building an MCP server (tools, prompts, resources) or an `agent()`.
 
+- An MCP server serves THREE primitives, and each reaches the client differently: a `tool()` is an action the MODEL calls (it may write); a `resource()` is read-only context the client APPLICATION lists and attaches by `uri` (reference docs, a schema, one record through a `{variable}` template); a `prompt()` is a message template with arguments the USER picks by name. Context a session opens with is a `resource()`; a workflow a user starts by name is a `prompt()`; data the model must fetch on its own mid-task stays a `tool()`, since a client shows the model only the resources attached to the conversation. Register each kind (`registerTools`/`registerPrompts`/`registerResources`) and list it on the server.
 - `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).
   - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) is the LEGACY way to publish a tool as an MCP resource — author a `resource()` and list it in `resources` instead; `toolMeta` is extra metadata on a tool entry. The two payload fields are per-type and supplying the other one is refused, because the engine stores it against neither. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — per-tool, and the only gate there is. ⚠ It is also what gives the tool a CALLER, on an `agent()` exactly as on an MCP server. `auth()` inside a tool whose entry names no table does NOT return null: the call answers a normal result carrying `{"code":"ERROR_FATAL","message":""}`, so the model reads a successful tool result and reports success while nothing is written. A caller token does not rescue it — the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.
   - `prompts?` / `resources?`: `prompt()` / `resource()` HANDLES (or names), or a `{ prompt, enabled?, auth? }` / `{ resource, enabled?, auth? }` wrapper. `auth` names the auth table and is what gives the stack a caller: a prompt/resource reading `auth()` behind an entry with none answers every `prompts/get` / `resources/read` with `-32603 "Access Denied"` (`export()` warns `toolset.primitive-reads-auth-ungated`). Listing one target twice THROWS; two resources with one `uri` on one server fail `export()` (`mcp.resource-uri-duplicate`). MCP-server only — `agent()` takes tools only.
   - `history?` is the server tier for its tools, prompts AND resources alike; an object's own `history` wins. The workspace tier (`workspaceConfig({ history })`) has `prompt` and `resource` keys, both default on.
   - `oauth?`: per-server sign-in; omit and nothing changes. Union on `mode`; `authTable` (REQUIRED, auth `table()` handle or name) is whose row the signed-in user is — `auth()` on the whole server, `t.auth` in its trigger. Hosted (the platform is the authorization server): `{ mode: "hosted", authTable, loginUrl }` — clients are sent to `loginUrl` (YOUR page, which is also the consent screen) with `mcp_request`; show `s.mcp.oauth.request`, sign the user in, then your endpoint calls `s.mcp.oauth.complete` with their `decision` and the page redirects to the URL it binds. External (your IdP issues tokens): `{ mode: "external", authTable, issuer, column, audience?, audienceAck?, claim?, claimAck?, preset?, allowedClientIds? }` — token `claim` (default `sub`) matched against `column`; `preset` is `auth0|clerk|workos|entra|okta|cognito|generic`. `loginUrl`/`issuer`/`audience` take `env("NAME")` (resolved per environment).
     - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` — users can edit it at most providers). Unknown `mode`/`preset` THROWS; so do the dropped `consent`/`branding`/`trustedClients`.
-- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
+- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order, `content` a string or an MCP content block: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
 - `resource({ name, uri, guid?, description?, docs?, mimeType?, title?, icons?, annotations?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP resource; takes `registerResources`. Clients address it by `uri`, never `name`.
   - `uri`: a literal (`"docs://readme"`, no `input`) or an RFC 6570 LEVEL-1 template (`"orders://{region}/{order_id}"`). It must start with a scheme; each `{variable}` is letters/digits/`_`, one per brace pair, never two adjacent. `input` must be EXACTLY the template's variables, each a single `text`/`int`/`decimal`/`bool`/`enum`/`email`/`uuid` — anything else THROWS. A value that does not convert is refused before the stack runs.
   - `response`: a string is returned as text; non-UTF-8 content (a file, binary) as a base64 blob. `mimeType?` omitted → derived from what the stack returns.

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.8
+# xanosdk v1.0.9
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -43,7 +43,7 @@ plain file read resolves them at the version you have.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
-- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when defining an `agent()`, `mcpServer()`, `prompt()` or `resource()`.
+- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
 - [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item for its AI agents.
 - [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Xano SDK — your Xano backend as TypeScript. `xanosdk deploy` ships your typed workspace (and an optional static frontend) to a live, auto-expiring ephemeral environment and prints its URL. init → deploy → URL.",
   "keywords": [
     "xanosdk",

package/skills/xano-backend/SKILL.md

@@ -14,8 +14,8 @@ description: >-
   FastAPI) unless the user asks for Xano.
 license: MIT
 metadata:
-  xanosdk-version: "1.0.8"
-  xanosdk-digest: "sha256:1473ad316197d3149c9222c5e54e206572a25319536a7fb2f3f22443db2c1088"
+  xanosdk-version: "1.0.9"
+  xanosdk-digest: "sha256:4c4c096cd062d4c4cf8066389104c392ea35aac52bffbd8220da4544f0d71f00"
 ---
 
 # Xano backend