soma.cell

Agents and LLM calls builtins

19 builtins of Soma 3.2.4 in the category Agents and LLM calls, with their exact signatures, as soma describe --builtins --json prints them.

think

think(prompt: String, system?: String, opts?: {max_tokens, timeout, max_rounds, tools_allowed, requires}) -> String

Call the configured LLM with tool-calling, multi-turn context, and budget enforcement. A think() offers the model every tool of the cell's face, or only those named in map("tools_allowed", ["lookup"]) (a call to another is refused and told to the model); requires lists model capabilities checked by soma check. A timeout is not retried (429/5xx are, up to 3 times).

deterministic · replay: an effect: not in the log — replay calls it again

Used in verified programs:

think_json

think_json(prompt: String, system?: String, opts?: {as, max_tokens, timeout, max_rounds, tools_allowed, requires}) -> Map | the `cell type` named by `as`

Like think(), but parses the response as JSON into a Map (tools are offered too: pass max_rounds 1 to keep the cost bound at one round). There is no schema option — check the fields yourself.

deterministic · replay: an effect: not in the log — replay calls it again

horde

horde(handler, inputs: List, opts?: {concurrency, max_attempts, budget_tokens, seed, snapshot, instance, on_result, apply, on_done, on_error}) -> String

Run handler (mark it [task]) once per input with a bounded pool of workers; returns the horde id (Cell:h1) at once. The queue is persisted with the program's data and resumes after a restart; each result is recorded — and on_result(result) / on_result(input, result) called — with the handler's last step, so once. budget_tokens: a hard ceiling (every think() reserves its bound first; state exhausted). on_error(input, error: {error, kind, detail}) after max_attempts (default 1); on_done(id) once at the end. Rounds: snapshot (handler takes (input, snapshot)), apply (in input order at the end), seed (reproducible random()), instance (per-agent memory). concurrency default 8, at most 1000. Without workers (soma test) it runs right after the caller commits.

deterministic · replay: pure

Used in verified programs:

vote

vote(handler, input, k: Int) -> Map

k agents (1..25) answer the same input; {winner, count, k, unanimous, errors, votes}. The most common answer wins, ties to the earliest voter. In a [task] step under serve / run the k calls run at once outside the lock, else in turn; each voter starts a fresh model context; a voter that raises counts in errors (all raising: the first error). Voters' writes are theirs — keep them read-only.

deterministic · replay: pure

horde_status

horde_status(id: String) -> Map

{state: running | cancelling | exhausting | done | cancelled | exhausted, total, queued, running, done, failed, cancelled, tokens, budget_tokens?} of a horde (its id names its cell).

deterministic · replay: pure

Used in verified programs:

  • agents/horde_audit, line 32: on progress() { return horde_status(batch.get("current") ?? "") }

horde_results

horde_results(id: String) -> List

The results of a horde in input order; () for a task not done (failed, cancelled or still queued).

deterministic · replay: pure

horde_cancel

horde_cancel(id: String) -> Bool

Stop a horde: no new task starts, running ones finish, on_done is called. false when it was not running.

deterministic · replay: pure

delegate

delegate(cell: String, signal: String, args...) -> Any

Invoke another cell's handler and return its result.

deterministic · replay: an effect: not in the log — replay calls it again

Used in verified programs:

set_budget

set_budget(max_tokens: Int) -> ()

Hard cap on LLM tokens; think() fails once exhausted.

deterministic · replay: pure

Used in verified programs:

tokens_used

tokens_used() -> Int

LLM tokens consumed since the budget was set.

deterministic · replay: pure

Used in verified programs:

tokens_remaining

tokens_remaining() -> Int

Tokens left in the budget, or -1 if unlimited.

deterministic · replay: pure

Used in verified programs:

trace

trace() -> List

Structured execution log: every think(), tool call, and approval.

deterministic · replay: pure

Used in verified programs:

clear_trace

clear_trace() -> ()

Empty the agent trace log.

deterministic · replay: pure

Used in verified programs:

clear_context

clear_context() -> ()

Reset the multi-turn LLM conversation history.

deterministic · replay: pure

Used in verified programs:

approve

approve(action: String) -> Bool

Human-in-the-loop gate. Answered by mock approve true|false in tests, by SOMA_APPROVE=always|never, or by a person at the terminal under soma run; otherwise (e.g. under soma serve) it RAISES kind "approval_required" — it never approves on its own.

deterministic · replay: an effect: not in the log — replay calls it again

Used in verified programs:

resume

resume(wait_id: String, answer) -> Any

Answer a stored wait (await approve(…) takes true/false) and run the rest of its handler; returns what the handler returns. Kind "not_waiting" when the id is not pending. Refused inside a tool.

deterministic · replay: pure

deliver

deliver(name: String, key, value) -> Any

Hand value to the handler stopped at await signal(name, key) and run the rest of it. Kind "not_waiting" when nothing waits for it.

deterministic · replay: pure

waiting

waiting() -> List<Map>

The stored waits, oldest first: {waiting, kind, message | name, key | until_ms, cell, handler, since_ms}.

deterministic · replay: pure

cancel_wait

cancel_wait(wait_id: String) -> Bool

Drop a stored wait without running the rest of its handler (what it wrote before the wait stays). Refused inside a tool.

deterministic · replay: pure