Object kinds

​

Object kinds

tableTrigger({
  name: "on-user-insert",
  table: users,
  actions: { insert: true },
  // Optional row filter, evaluated by the DATABASE before the stack runs — so it
  // names the SQL pseudo-tables with col(), NOT the t handle. Rejected with
  // `truncate`; insert cannot read OLD.*, delete cannot read NEW.*.
  search: cmp(col("NEW.email"), "!=", c.text("")),
  stack: (t) => [
    // t.new("email") is typed to the row; t.action is the op; t.old is null (insert-only).
    s.db.add({ table: auditLog, row: { email: t.new("email"), event: t.action } }),
  ],
});

workflowTest({
  name: "signup_works",
  tags: ["smoke"],
  // datasource omitted on purpose — "" is an EMPTY datasource, not "no datasource".
  stack: [
    s.function.call({ fn: createUser, input: { email: "a@b.c" }, as: "created" }),
    s.expect.to_be_defined({ expr: ref("created") }),
    s.expect.to_equal({ expr: ref("created.status"), value: c.text("ok") }),
    // A regex assertion takes a PATTERN, so build it with `c.regex(...)`.
    s.expect.to_match({ expr: ref("created.id"), value: c.regex("^usr_[a-z0-9]+$") }),
  ],
});

query({
  name: "score",
  verb: "POST",
  input: { score: input.int({ required: true }) },
  tests: [
    {
      name: "adds one",
      input: { score: c.int(1) },
      // Subject first — argument order is the assertion.
      expect: [expect.to_equal(resp(), c.int(2))],
    },
  ],
  stack: [
    // Returns 2 while "adds one" runs; does nothing on a real request. A name
    // no test declares throws at compile time.
    s.set_var("total", c.expression("$input.score + 1"), {
      mock: { "adds one": c.int(2) },
    }),
  ],
  response: ref("total"),
});

const chat = realtimeServer({ name: "chat", enabled: true });

const room = realtimeChannel({
  name: "rooms/{room_id}",           // `input` types the PATH params
  server: chat,
  input: { room_id: input.int() },
  publish: { who: "authenticated" },
  conversation: { enabled: true, limit: 50 },   // client-visible transcript
});

realtimeMessage({
  name: "send",                      // `input` types the message PAYLOAD
  channel: room,                     // the handle carries the server too
  input: { body: input.text({ required: true }) },
  deliverTo: "channel",              // or "sender" (request/response) / "others"
  stack: [s.debug.log({ value: inp("body") })],
});

• An empty return denies, and so does a crash. connect and join are gates: return { allowed: c.bool(true) } or any truthy value to admit. A stack that falls through, or a gating trigger with no response, refuses everyone — and a raise refuses too, because the gate is seeded with a deny it keeps when the stack throws. Both failure modes lock the door, so the risk to plan for is a self-inflicted lockout, not a breach: guard every drill inside a gate with ref(path, { safe: true }), since db.get binds null on a miss. export() warns on the missing response; nothing can warn about the raise. Gating is opt-in — a server with no connect trigger admits everyone.
• Only null drops a message. In a deliver trigger (per recipient) and in a message handler, false/0/"" all deliver the message unchanged, and a crash broadcasts the sender’s original unvalidated payload. Return null to suppress. So a redaction check written as a boolean sends the very message it was meant to hide. Per-viewer redaction also takes two objects: the deliver trigger and delivery: { perRecipient: true } on its channel. Either half alone delivers the payload unchanged to everyone, so a gate whose return semantics are perfect still ships unredacted if the flag is missing — and the flag costs a stack per recipient per message, so it is opt-in. export() warns on both halves.
• conversation: { enabled: true } alone stores nothing. limit defaults to 0, and 0 means retain none. Always pass a limit. What a handler broadcasts is the stored row, so broadcast everything a future joiner needs to render it.
• An idle socket is reaped after ~10 minutes. A listen-only client (feed, dashboard, presence sidebar) must send { action: "ping" } or any frame periodically, or it silently drops and reconnects forever.
• s.realtime.publish is the push direction, and it is fail-soft. It bypasses the channel’s publish.who (authorization belongs in your stack), does not invoke the named message’s handler, and swallows a missing or disabled server — a mis-targeted publish is silent. Pass the server handle and a filled-in path (room.getChannel({ room_id: 42 })), never the template — a constant channel still carrying {param} throws at author time, and a constant server or channel naming nothing this workspace registers warns at export.

// Auth is PER-TOOL and works like a query's: name an auth table({ auth: true }).
mcpServer({ name: "books", tools: [{ tool: searchTool, auth: users }] });

const assistant = agent({
  name: "assistant",
  llm: { type: "xano-free", systemPrompt: "Be helpful.", prompt: "Answer the question." },
  // Pass the handles directly; the `{ tool, enabled?, auth? }` wrapper (above)
  // is only for per-tool auth or `enabled: false`.
  tools: [searchTool],
});

// Agents have NO public endpoint — invoke them in-stack from any host with a stack.
query({
  name: "ask", verb: "POST", apiGroup: api,
  input: { question: input.text({ required: true }) },
  stack: [s.ai.agent.run({ agent: assistant, args: obj({ question: inp("question") }), as: "answer" })],
  response: { text: ref("answer.result") },
});

• The run result is an envelope, not the completion. The model’s text is at .result — ref("answer") is the whole metadata object (finishReason, steps, …). Both are typed, so InferResponse reflects either.
• llm is a provider-discriminated union — anthropic / openai / google-genai / xano-free (which needs no API key) — each with its provider’s typed fields.
• Structured output types the call site. Author output: { schema: { … } } on the agent with the input.* catalog and .result is typed from it wherever the handle is passed — no second witness. The type-only resultShape is only for overriding that, or for an agent referenced by bare name.
• String settings are Twig-templated at run time. The args you pass to s.ai.agent.run become {{ $args }} (env vars are {{ $env.NAME }}), which is how an endpoint’s inputs reach the prompt. Numeric and boolean fields are not templated. Build a dynamic arg with obj({...}), not c.obj.
• mcpServer().getUrl(HOST) derives the Streamable-HTTP endpoint from the def, the same contract as query.getPath(). Resolve once — handing the result back in as a HOST throws rather than append a second endpoint path. Agents expose only getCanonical().

const summarize = prompt({
  name: "summarize",
  input: { post_id: input.int({ required: true }) },
  stack: [s.db.get({ table: posts, fieldValue: inp("post_id"), as: "post" })],
  response: ref("post.title"), // a string is one user message
});

const post = resource({
  name: "post",
  uri: "posts://{post_id}", // each {variable} is exactly one input field
  mimeType: "application/json",
  input: { post_id: input.int({ required: true }) },
  stack: [s.db.get({ table: posts, fieldValue: inp("post_id"), as: "post" })],
  response: ref("post"),
});

mcpServer({ name: "posts", tools: [searchTool], prompts: [summarize], resources: [post] });

• s.mcp.elicit re-runs the stack. It asks the client’s user mid-call; when they answer, the whole stack runs again from the top. Ask first, then act — export() warns when a write comes before an elicit. Clients older than MCP 2026-07-28 get { action: "cancel" }, so handle it. s.mcp.progress reports progress to a client that asked for it.

​

Microservices

export const echo = microservice({
  name: "echo",
  deployment: {
    replicas: 2,
    containers: [{
      name: "echo",
      image: "ealen/echo-server:latest",
      ports: [{ servicePort: "8080", containerPort: "80" }],
      resources: { cpu: "50m", ram: "256Mi" },
    }],
  },
});

s.microservice.request({ as: "res", host: echo, path: "/health" });

• The engine reports the microservice broken (an image that won’t pull, a container that won’t start) — the deploy exits 4. Waiting longer cannot change that answer, and a URL and a ✓ printed over a dead workload is not a successful deploy. This is the default; there is no flag to turn it off.
• It simply hasn’t reported ready by the end of the wait — a warning, exit 0. The backend is live and a slow container usually follows moments later. Pass --require-microservices to make that exit 4 too, which is what CI wants: nobody is there to find out whether “should come up shortly” happened.

// WRONG, for either field.
microservice({ name: "app", registryAuth: { dockerconfigjson: process.env.REGISTRY_JSON! } });

// A builtin container: name the variable, and the secret stays out of the bundle.
env: [{ name: "API_KEY", fromEnv: "STRIPE_SECRET" }]

// A helm chart: the same reference, for a value at any depth.
chart: { values: 'auth:\n  token: "${env.STRIPE_SECRET}"\n' }

1. Leave registryAuth unset — a public image, or a pull credential attached to the microservice outside this workspace. Nothing then carries a credential.
2. Accept that the tree is secret-bearing — keep workspace.json and any pulled tree out of git, or rotate the credential once it lands there.