Repository navigation
Async Capabilities
A capability declared async: true is slow: a report, a long count, an AI call. In
Snap it never runs in the request:
the person gets a Track card: Task at once, a job of the queue
runs it as that person, and they are notified when it ends. Every other channel (pages, REST, MCP, the command line)
still calls it directly, as before. Since 2.23.0.
/caligrafy-quill:new-capability reading_report books:read read-only async: the books read this year by every reader, by month
Claude writes the capability with async: true and makes sure a worker runs the queue (a job on queue_work in
application/config/schedule.php).
Check before you say OK:
- in Snap, asking for it shows a Task card that goes from Waiting to start to Working on it, then its result;
-
php caligrafer.php queue work --onceruns the waitingsnap_task_runjob.
-
The tables.
docker compose exec dev-box php caligrafer.php platform installcreates the queue'scaligrafy_jobsand Snap's tables (the deploy step does too). -
Declare it.
Or leave the attribute as it is and make it async for Snap only, with the hint
#[Capability(name: 'reading_report', description: '...', scope: 'books:read', readOnly: true, async: true)]
asyncinapplication/config/snap.php;workinggives the lines the card shows, in turn, while it runs:return [ 'cards' => [ 'reading_report' => ['async' => true, 'working' => ['Counting the books…']], ], ];
-
A worker. Something must run the queue: a job on
queue_workinapplication/config/schedule.php(array('name' => 'queue', 'capability' => 'queue_work', 'every' => '1m', 'timeout' => 55), which Caligrafy Cloud andserver startrun), orphp caligrafer.php queue workon your own server. See Background jobs.
- A read starts as a task at once; a change starts after the person confirms its Ask: Confirm card. Only a signed-in
person can start one (a visitor gets
unauthenticated). -
Snap\Tasks::start()writes a row ofcaligrafy_snap_tasks(the person, the capability, the inputs,queued) and pushes the jobsnap_task_runto the queue, with 3 attempts and a 120 second timeout. - The worker runs the capability with
Capabilities::call()as the person who asked: their user on thewebchannel, so their permissions, not the queue's full access. Its checks, validation and audit are those of any call. - It ends in one of three states, keeps the card it ended with, and notifies the person on every channel they turned on (Notifications):
| Status | Label | When | The card it ends with |
|---|---|---|---|
queued |
Waiting to start | pushed, or put back for the queue's next attempt after an error | |
running |
Working on it | the worker started it | |
done |
Done | it answered | the Show card of the result |
needs_input |
Needs your answer | it refused an input (invalid) |
the Ask card of what it refused; answering it starts a new task |
failed |
Could not finish | it refused (forbidden, unauthenticated, not_found, conflict), the person no longer exists, or the queue's retries ran out |
a notice |
The Track card shows where it is, live, with its steps (Asked, Started, then how it ended); Home shows it in progress, then just done. A person sees only their own tasks.
Reference: Snap\Tasks,
Snap\Tasks::async(),
Queue::push().
async changes nothing outside Snap: REST, MCP, the JS client, Route::page, Route::form and
php caligrafer.php call run it in the request, as any capability. To run any capability later from your own code,
push it to the queue yourself: Queue::push('build_report', ['month' => '2026-11'])
(Background jobs).
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)