Actions — permission-checked UI buttons

An action is a button declared as metadata: where it appears (locations), when it's visible (visible), who may run it (requiredPermissions), and what it executes — an inline sandboxed script, a registered server handler, a flow, or a URL. The same declaration renders in the Console, executes over REST, and (with an explicit opt-in) becomes an AI tool over MCP.

The types you'll actually use:

Define your first action

From the bundled Todo example — a "Mark Complete" button on the task list and record header:

import { defineAction } from '@objectstack/spec/ui';

export const CompleteTaskAction = defineAction({
  name: 'complete_task',
  label: 'Mark Complete',
  objectName: 'todo_task',          // which object this action belongs to
  icon: 'check-circle',
  type: 'script',
  target: 'completeTask',           // resolved to the handler registered below
  locations: ['record_header', 'list_item'],
  successMessage: 'Task marked as complete!',
  refreshAfter: true,
  ai: {
    exposed: true,
    description: 'Mark a todo task as complete. Use when the user says a task is done or finished.',
  },
});

Register it in your stack — top-level actions carrying an objectName are merged into that object automatically (and ordered by order):

export default defineStack({
  // ...
  actions: Object.values(actions),
});

Give it server behavior — two paths

Path A: inline body (sandboxed)

Self-contained logic ships inside the metadata and runs in the server sandbox — signature (input, ctx), with ctx.api.object(name) for data access, a 5-second default timeout, and declared capabilities:

export const MarkDoneAction = defineAction({
  name: 'showcase_mark_done',
  label: 'Mark Done',
  objectName: 'showcase_task',
  type: 'script',
  body: {
    language: 'js',
    source:
      "var id = ctx.recordId || (ctx.record && ctx.record.id);" +
      "if (!id) throw new Error('No record to mark done');" +
      "await ctx.api.object('showcase_task').update({ id: id, done: true, progress: 100 });" +
      "return { ok: true, id: id };",
    capabilities: ['api.write'],
  },
  successMessage: 'Task marked done.',
  visible: 'has(record.done) && record.done != true',
  locations: ['list_item', 'record_header', 'record_section'],
  refreshAfter: true,
});

Body-carrying actions are registered automatically at boot.

ctx.record.done = true;      // ❌ discarded — even though `done` is a declared field
return { ok: true };         //    the action reports success, the record is unchanged

await ctx.api.object('showcase_task').update({ id: ctx.recordId, done: true });  // ✅ persists

ctx.record.done = true;
await ctx.api.object('showcase_task').update(ctx.record);   // ✅ lands — not reported

Path B: a registered handler (full TypeScript)

For logic that belongs in real source files, point target at a handler name and register it in your config's onEnable lifecycle hook:

import type { ActionHandlerContext } from '@objectstack/spec/ui';

export async function completeTask(ctx: ActionHandlerContext): Promise<void> {
  const { record, engine } = ctx;   // ctx = { record, params, user, session, engine }
  await engine.update('todo_task', record.id as string, {
    status: 'completed',
  });
}

Annotate ctx with the published ActionHandlerContext, never a local copy of it: a hand-rolled context interface drifts from the contract the moment either side moves, and the drift is silent because the copy is what your handler is checked against. (The contract's own docblock asks for ActionHandler; that is a function type, so it fits an arrow-function handler assigned to a const, while a function declaration like the one above annotates its parameter instead.)

Write only the fields the action owns — and read that literally, because a handler's ctx.engine runs elevated (isSystem). The read-only strip that protects a server-owned column from an ordinary caller is gated on not being a system write, so it does not run on a handler's write at all. What a handler names, lands. A server-owned field is therefore more dangerous here than in a form PUT, not less.

completed_date is the example. It is readonly on todo_task — the server owns it, and the object's beforeUpdate hook stamps it on the completion transition. Adding completed_date: new Date().toISOString() to the write above looks harmless, and on that transition it is: the hook overwrites it. But a completion write that is not a transition — re-completing a task that is already completed — is not stamped, so nothing overwrites the handler's value and nothing strips it either, and the action silently replaces the real completion timestamp with "now". That is why the snippet sends status alone.

await ctx.engine.find('todo_task', { where: { status: 'completed' } });
await ctx.engine.find('todo_task', { where: { amount: { $gt: 100 } }, fields: ['id', 'subject'], limit: 50 });
await ctx.engine.find('todo_task', {});   // the unfiltered read

await ctx.engine.delete('todo_task', record.id as string);        // one row
await ctx.engine.delete('todo_task', ['tsk_0001', 'tsk_0002']);   // a set

export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);
};

Bind it to the UI

locations is the primary binding — the action appears wherever it declares:

Surfaces can also reference actions by name:

// List views — row and bulk menus. These are LIST-VIEW keys, so they nest
// under `list` (or a `listViews` entry) — never at the container top level:
// `ViewSchema` is a strict object and rejects them there.
defineView({
  // ...
  list: {
    // ...
    rowActions: ['complete_task'],
    bulkActions: ['showcase_bulk_reassign'],
  },
});

// Record pages — a quick-actions bar
{ type: 'record:quick_actions',
  properties: { location: 'record_section', actionNames: ['showcase_mark_done'] } }

// App navigation — an action as a nav item
{ type: 'action', actionDef: { actionName: 'crm_convert_lead' } }

// App navigation — deep-link auto-run on an object entry: land on the
// object's list surface, then run the declared action once
{ type: 'object', objectName: 'sys_environment', runAction: 'create_environment' }

Declare the bulk dispatch contract

A list view can wire the same action two ways, and the two hand your body opposite input:

Say which one you wrote the body for, with the same key and the same two values the def uses:

defineAction({
  name: 'export_zip',
  type: 'api',
  target: '/api/v1/export/zip',
  execution: 'aggregate',   // this body reads params._selectedIds
});

os validate / os lint / os build then refuse a list view that wires it the other way (action-dispatch-contract-mismatch), naming the action, the view and both contracts. Without the declaration both mismatches fail silently, in opposite directions: an aggregate body wired bare-string reads _selectedIds as undefined, takes its single-record branch and reports success for one row out of ten; a per-record body wired aggregate finds no recordId and throws its own "nothing selected", which reads like a selection bug. Nothing else can catch it — recordId and _selectedIds are both built-in action params, so the strict params gate admits either bag without a word.

Collect input and shape the UX

• params — prompt the user for input before execution. Prefer field-backed params ({ field: 'due_date' }) which inherit the object field's label, type, validation, and widget config; inline params ({ name, label, type, required, options }) cover the rest. defaultFromRow prefills from the current record. The console renders each param through the same field widgets as the record form (objectui ADR-0059), so any FieldType works — a file param shows a real upload control (multiple / accept / maxSize honored), lookup a record picker, date a date picker, richtext the rich-text editor, and so on.
• confirmText — confirmation dialog before running.
• successMessage / errorMessage / refreshAfter — post-run feedback and an automatic data refresh.
• undoable — on a single-record update, the success toast offers an Undo that restores the record's prior field values (Ctrl+Z works too). The runtime only captures the prior values when this flag is set, so an action that omits it gets no Undo.
• resultDialog — a one-time reveal dialog for output the user must copy (generated tokens, export links).
• variant / icon / order — presentation and sort position.

Permissions and visibility

• requiredPermissions: ['can_close_tickets'] is a dual-surface gate (one declaration, two enforcement points): the server rejects unauthorized calls with 403, and the UI hides or disables the button for the same users. Unset means no gate beyond object CRUD permissions — except that a flow action whose target is an elevated self-triggered flow is refused to every caller but the system principal either way (the flow row below). Referenced capabilities must exist — os lint checks that.

• visible is a CEL predicate evaluated fail-closed: an expression that throws hides the action silently. Two rules save real debugging time:

  1. Always prefix record fields — record.status != "closed", never a bare status, which faults as an undeclared identifier.
  2. Guard with has() — a record-scoped predicate on list_item binds a LIST ROW, which carries only the columns that view projects. Reading a field the list does not show aborts the expression with No such key, and fail-closed means the button simply is not offered — indistinguishable from the gate having said no. has(record.x) && … answers false instead.

  Add && record.x != null only when the value is then traversed (record.x.k), called (record.x.size()), ordered (< <= > >=), negated (!record.x) or used with in — those fault on a projected NULL. A plain == / != against a literal never does, so has() alone is the whole guard there. Prefer the minimal form: an over-guarded predicate is the pattern the next author copies.

  Compound && / || predicates are fully supported — see the formulas guide for CEL syntax.

• requiresFeature ties visibility to a feature flag (compiled into a visible predicate).

Authorization inside an action

An action body and a registered handler both run elevated: ctx.api and ctx.engine carry isSystem, so they bypass row- and field-level security by design (that is what lets an action do work the caller cannot do directly). The consequence is that any caller-specific rule has to be re-established inside your handler — and the predicate most people reach for first does not work:

if (!ctx.record?.id) return refuse();   // ❌ always false — never refuses anything

Before dispatch, the platform loads the subject row in your caller's own scope. If that read comes back empty — the row is invisible to them under row-level security, or the id names nothing — the dispatcher still puts the recordId from the request onto ctx.record.id, because a new-record / record-less action legitimately needs it there. So ctx.record.id is present either way, and the guard above passes for a caller who cannot see the row.

The signal that does distinguish them is ctx.recordLoadDenied:

// ✅ the caller-scope load did not deliver the row — do not act on it
if (ctx.recordLoadDenied) {
  throw Object.assign(new Error('Record not available'), { code: 'RECORD_NOT_FOUND' });
}

Set ctx.recordLoadDenied aside only when your action is meant to run without a readable subject row (an "import this id from elsewhere" action, say). The default for a row-scoped action on a private object is to refuse.

Flow actions. A type: 'flow' action hands its target flow the same record — record.id stamped the same way — and the flow run's context (AutomationContext, the @objectstack/spec contract) declares the same key in the same spelling, recordLoadDenied?: true, so a runAs: 'system' flow has something to guard on before it acts on a row its invoker could not read. On the flow face the key is populated since #15168: dispatchFlowAction takes the producer's load outcome and spreads the signal into the context it hands automation.execute, on both doors — the REST /actions endpoint and the MCP run_action bridge — so a flow run receives this key exactly when a handler would. A runAs: 'user' flow needs no guard — it re-derives the caller's scope on its own reads, and the stub resolves to nothing.

Call it over REST

Every action is also an endpoint — the Console button and the API call run the same gate and handler:

curl -b cookies.txt -X POST \
  https://your-app.example.com/api/v1/actions/todo_task/complete_task \
  -H "Content-Type: application/json" \
  -d '{ "recordId": "rec_123", "params": {} }'
# → 200 { "success": true, "data": <your handler's return value> }

The URL names the action by its name, never by target. target binds the action to whatever runs it — a handler key here, a flow id for type: 'flow', a URL for type: 'url' — so it is an implementation detail: the server resolves your declaration by name and derives the handler key from it. Rename the underlying function freely; as long as the declaration's target follows, the public URL is unchanged.

Failures speak HTTP — the status code is the signal (#3962):

• 400 — the action ran and rejected (a business rule said no, or validation failed — then with error.details.fields[] to anchor the input).
• 404 / 403 / 503 — it never dispatched: no such action, denied, service unavailable. A url/modal/form/api type with no server dispatch is also a 400.
• 500 — it crashed: a TypeError in your handler, a driver error, a sandbox timeout. A deliberate throw new Error('…') is a 400 rejection, not a crash.

Full table in the error catalog. The client SDK folds all of it into one { success, data?, error? } result.

Global (object-less) actions post to /api/v1/actions/global/:action, or to /api/v1/actions//:action with the object segment left empty. For credentials, see API Authentication.

The endpoint dispatches on the declared type, exactly like the MCP run_action tool — so the same URL invokes a script handler or a flow:

Headless actions: declare it, then hide it

An action that should be callable but not appear in the UI is still a declared action. Hiding is a property you set; it is not the absence of a declaration:

defineAction({
  name: 'recalculate_commissions',
  type: 'script',
  target: 'recalcCommissions',
  locations: [],                            // no UI surface
  requiredPermissions: ['finance.admin'],   // still gated
  // `ai.exposed` is false by default — no MCP tool either
})

You keep the capability gate, the param contract, the audit trail, and Setup visibility for admins. A declaration that no surface renders costs you nothing.

Action 'recalc' on 'crm_account' has no declaration — add
`defineAction({ name: 'recalc', … })`, or register the handler under a declared
action's `target`.

Expose it to AI (MCP)

Actions are not AI-visible by default. Opting in takes two fields — and makes the action a governed MCP tool alongside the data tools:

ai: {
  exposed: true,
  description: 'At least 40 characters explaining when an agent should use this action.',
}

Only headless-callable types appear (script with body or handler, flow); url/modal never do. The caller's identity and requiredPermissions are enforced per invocation. Details: Actions as Tools and Connect an MCP Client.

Troubleshooting

Related

• Actions as Tools — the AI exposure model in depth
• Views — rowActions / bulkActions binding
• Action protocol — the full spec narrative
• Action schema reference — every property, generated from the spec