@xano/sdk 1.0.10 → 1.0.11

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.10
+# xanosdk v1.0.11
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -659,7 +659,8 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
   Fix: `xanosdk routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
   plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
-  URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+  URLs lifted to `wss://h/ws/<tenant>:<canonical>`), `mcpUrl("notes_mcp", baseUrl)` (an MCP
+  server's address to show a user or hand a client; browser JS cannot call it). A rename is a type error, not a 404.
 - **Request types without the def.** `routes.gen.ts` also exports types-only `RouteInputs`,
   `ChannelInputs`, `MessageInputs` (and `MessageName`), keyed like `ROUTES`, `CHANNELS`, and
   `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A
@@ -770,6 +771,8 @@ core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-
 - A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) — the body threw; use the preloaded globals, the surface's bindings, and `capture`. `llms/lambda.md`.
 - `Unable to locate request.` (404) on an endpoint that deployed — a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.
 - A browser call fails on a missing `access-control-allow-origin` while deploy looks fine — CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.
+- 403 `Forbidden: Origin not allowed` from an MCP server URL — the request came from a browser; MCP endpoints refuse every `Origin`, so call them server-side. `llms/kinds-agent-mcp.md`.
+- `ERROR_FATAL` `The free model is not available in this process.` — an `xano-free` agent run on the Xano Engine on this machine; it runs only on Xano's cloud. `llms/kinds-agent-mcp.md`.
 - A websocket is closed right after the handshake — a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.
 - `to_throw failed - response is ok` around an auth-refused call — `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.
 - Output reads `Hi [object Object]` — a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.
@@ -868,6 +871,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 - 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).
+  - ⚠ Refuses any request carrying a browser `Origin`, preflight too: 403, JSON-RPC `-32000` `Forbidden: Origin not allowed`. One with no `Origin` (curl, a server, an MCP client) is served; the bundle cannot admit an origin, so call it server-side, never from browser JS.
   - `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.
@@ -888,6 +892,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 - `s.mcp.oauth.revoke({ mcp_server, user_id? | grant_id? | all?, as? })` — end hosted sign-ins on a server: EXACTLY ONE of `user_id`, `grant_id`, `all: c.bool(true)`, else `export()` fails (`mcp.oauth-revoke-target`). Binds `{ revoked }`.
 - `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` — an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` — the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.
   - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
+  - `xano-free` runs only on Xano's cloud: on the Xano Engine on this machine a run fails `ERROR_FATAL` `The free model is not available in this process.` — use a keyed provider there.
   - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
   - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
   - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, allowToolExecution: c.bool(true), as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. ⚠ An agent with tools needs `allowToolExecution: c.bool(true)` on the run: unset, its tools are OFF and it answers without them (warns `stack.agent-tools-off`).
@@ -1250,7 +1255,7 @@ Microservices (the `microservice()` def and the statement that calls it):
 - `inp(name: string) => Value` — Reference a function/endpoint input → tag "input". Resolves ONLY against the `input` block of the def it sits in — a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it — an undeclared input is never bound, so the call fails identically with the value present. A dotted path drills INTO a declared input (`inp("action.amount")` needs a declared `action`).
 - `col(name: string) => Value` — Reference a table column → tag "col".
 - `auth(path?: string) => Value` — Reference the authenticated identity (auth("id") → $auth.id) → tag "auth".
-- `caught(path?: "code" | "message" | "name" | "result") => Value` — Read the caught error inside an s.try_catch CATCH arm → tag "trycatch". Valid ONLY there — it reads empty in the try/finally arms and outside the statement. Those four fields are all the engine binds (result is the attached payload); bare caught() is the whole error record. ⚠ For an ENGINE-raised exception only `code` and `name` are populated; for an `s.throw`, `message` is the fixed string "Throw Error Statement" and your text is in `result`. So `caught("name")` is useful in both cases and `caught("message")` in NEITHER.
+- `caught(path?: "code" | "message" | "name" | "result") => Value` — Read the caught error inside an s.try_catch CATCH arm → tag "trycatch". Valid ONLY there — it reads empty in the try/finally arms and outside the statement. Those four fields are all the engine binds; bare caught() is the whole error record. `code` is the error type: `ERROR_FATAL` for an engine error, a precondition's `error_type` (`ERROR_CODE_ACCESS_DENIED`, …), `ERROR_CODE_THROWN_ERROR` for `s.throw`. `message` is the error text (a precondition's `error`, the engine's, an LLM provider's) EXCEPT for `s.throw`, where it is the fixed "Throw Error Statement" and your value is in `result`. `name` is `s.throw`'s `name` (empty without one), else a label (`Exception`, `Access Denied`). ⚠ An `s.ai.agent.run` provider failure binds `result: { name: "AI_APICallError", statusCode, isRetryable, data }`; branch a fallback on `withFilters(caught("result"), fl.get("statusCode"))` (401: the key was refused). The path takes only the four names; reach deeper with `fl.get`.
 - `toolset(path: "token" | "params" | `params.${string}`) => Value` — Read a toolset-scoped binding inside a tool → tag "toolset". The engine binds two: token (the calling URL's token, null when absent) and params (its parameters, as an object); a dotted params.<key> reads one parameter out of that object. Bound only while a tool runs under its toolset — anywhere else it reads empty.
 - `env(name: string) => Value` — Read a WORKSPACE environment variable (set via workspaceConfig({ env }) or the dashboard) → `$env.NAME`. Compiles to tag "setting" with the plain name. env("remote_ip") reads a user var named remote_ip, not the caller IP — use sys.remoteIp() for that. A name that does not exist resolves to NULL rather than erroring, so a typo deploys clean and fails downstream of the value: prefer typedEnv(config), which turns the names that config declares into properties (E.STRIPE_KEY), and export() warns stack.env-undeclared on any env() or bare setting() outside the declared set once a config declares env at all.
 - `setting(name: string) => Value` — Reference a workspace setting → tag "setting". Built-in system vars are $-prefixed settings, e.g. setting("$remote_ip"); prefer the typed sys.* accessors.
@@ -1622,7 +1627,8 @@ stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get
 - `fl.url_hasarg(key: text): text`
 - `fl.yaml_encode(options?: bool, inline?: int, indent?: int): text`
 
-Zero-argument filters — call as `fl.<name>()`; an argument is a compile error: abs, acos, acosh, addslashes, array_entries, array_keys, array_lower, array_pop, array_shift, array_shuffle, array_values, asin, asinh, atan, atanh, avg, base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, bitwise_not, capitalize, ceil, cos, count, create_object_from_entries, decbin, dechex, decoct, deg2rad, empty, escape, even, exp, first, flatten, floor, from_utf8, hex2bin, hexdec, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, json_decode, json_encode, last, list_encodings, ln, log10, lower, ms_to_secs, not, null, octdec, odd, product, querystring_parse, rad2deg, reverse, rsort, safe_array, secs_to_ms, sin, sort, sql_alias, sql_esc, sqrt, strip_accents, strlen, sum, tan, text_escape, text_unescape, to_bool, to_decimal, to_expr, to_geo_linestring, to_geo_multilinestring, to_geo_multipoint, to_geo_multipolygon, to_geo_point, to_geo_polygon, to_int, to_text, to_utf8, uid, upper, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, url_parse, uuid4, xml_decode, yaml_decode.
+Zero-argument filters, by operand type — call as `fl.<name>()`; an argument is a compile error. array: array_entries, array_keys, array_lower, array_pop, array_shift, array_shuffle, array_values, count, first, flatten, last, reverse, rsort, safe_array; comparison: bitwise_not, empty, even, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, not, odd; geo: to_geo_linestring, to_geo_multilinestring, to_geo_multipoint, to_geo_multipolygon, to_geo_point, to_geo_polygon; math: abs, acos, acosh, asin, asinh, atan, atanh, avg, ceil, cos, deg2rad, exp, floor, ln, log10, product, rad2deg, sin, sqrt, sum, tan; misc: null; other: sort; security: uid, uuid4; text: addslashes, capitalize, escape, from_utf8, list_encodings, lower, querystring_parse, sql_alias, sql_esc, strip_accents, strlen, text_escape, text_unescape, to_utf8, upper, url_parse; timestamp: ms_to_secs, secs_to_ms; transform: base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, create_object_from_entries, decbin, dechex, decoct, hex2bin, hexdec, json_decode, json_encode, octdec, to_bool, to_decimal, to_expr, to_int, to_text, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, xml_decode, yaml_decode.
+`fl.reverse()` reverses a list only: on a text value it answers the text UNCHANGED, with no error.
 
 Variadic filters — they take arguments, but no declared list, so the count is not checked: sprintf.
 

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.10
+# xanosdk v1.0.11
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -128,7 +128,7 @@
       {
         "name": "caught",
         "signature": "(path?: \"code\" | \"message\" | \"name\" | \"result\") => Value",
-        "description": "Read the caught error inside an s.try_catch CATCH arm → tag \"trycatch\". Valid ONLY there — it reads empty in the try/finally arms and outside the statement. Those four fields are all the engine binds (result is the attached payload); bare caught() is the whole error record. ⚠ For an ENGINE-raised exception only `code` and `name` are populated; for an `s.throw`, `message` is the fixed string \"Throw Error Statement\" and your text is in `result`. So `caught(\"name\")` is useful in both cases and `caught(\"message\")` in NEITHER."
+        "description": "Read the caught error inside an s.try_catch CATCH arm → tag \"trycatch\". Valid ONLY there — it reads empty in the try/finally arms and outside the statement. Those four fields are all the engine binds; bare caught() is the whole error record. `code` is the error type: `ERROR_FATAL` for an engine error, a precondition's `error_type` (`ERROR_CODE_ACCESS_DENIED`, …), `ERROR_CODE_THROWN_ERROR` for `s.throw`. `message` is the error text (a precondition's `error`, the engine's, an LLM provider's) EXCEPT for `s.throw`, where it is the fixed \"Throw Error Statement\" and your value is in `result`. `name` is `s.throw`'s `name` (empty without one), else a label (`Exception`, `Access Denied`). ⚠ An `s.ai.agent.run` provider failure binds `result: { name: \"AI_APICallError\", statusCode, isRetryable, data }`; branch a fallback on `withFilters(caught(\"result\"), fl.get(\"statusCode\"))` (401: the key was refused). The path takes only the four names; reach deeper with `fl.get`."
       },
       {
         "name": "toolset",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "The official TypeScript SDK for Xano, one platform to build, run and govern AI-built software. Your coding agent writes the backend in TypeScript, you run it on the Xano Engine on your machine, then deploy it to Xano.",
   "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.10"
-  xanosdk-digest: "sha256:9bd1fa955f2ee4b8f922e884435efaa2ed209c741f1578b2d3181ebff2bc5fd2"
+  xanosdk-version: "1.0.11"
+  xanosdk-digest: "sha256:c5d35da65c9b45a105277ba0dec5d798f6fcb6239a99f50db8f6327d1c7abca6"
 ---
 
 # Xano backend