Tools & approvals

Some things an assistant does only read data. Others change something outside Synaplan — send mail, write a file, call an HTTP API. This page is how those actions are listed, how an operator decides what may run on its own, and how you approve the rest.

Approvals and custom HTTP tools are off until an operator turns them on. The tool registry itself is on by default (a kill-switch: turn it off to restore the older per-loop catalogues).

In three sentences

Every callable — web search, file tools, connected apps, and your own HTTP APIs — lives in one registry. Read-class tools run; write-class tools wait for you; destructive tools stay blocked unless you change the default. When something waits, a card appears in the chat and under Manage → Automations → Approvals.

Who this is for

You are… What you do
Everyone Approve or reject a waiting action in chat or in the Approvals inbox. Pick instant email or a daily digest.
An operator Turn approvals and custom HTTP tools on, set the read / write / destructive defaults, and set how long a request waits.

What you see

Chat

When a write-class tool needs consent, the answer shows an approval card: what it wants to do, Approve, Reject, and Always allow for this assistant (a personal override that never loosens a hard block). A rejected or expired request does not run.

Approvals inbox

Manage → Automations → Approvals (/channels/approvals) lists Waiting and Decided. Open a row to jump back to the chat or the Saved Task that asked. The page is hidden while TOOLS.APPROVALS_ENABLED is off.

You choose Email me as soon as something waits or Send me a daily summary. Pending requests expire after the operator's window (default 72 hours).

Saved Tasks

An unattended run that hits a write-class tool pauses. The task card shows that it is waiting. Approve it in the inbox (or from a link on the task) and the run continues; let it expire and that step is skipped. Three consecutive failures still auto-pause the task, as before.

Interactive chat approvals run the tool when you approve. They do not continue the turn as a new assistant message — that follow-up is not shipped yet.

Custom HTTP tools

When TOOLS.CUSTOM_HTTP_ENABLED is on, Manage → Connections (/channels/connections) grows a Custom tools section under your mailboxes and folders.

  • Add a custom tool — name, title, what it does, HTTP method and URL, an optional JSON body template, and a class: Reads data, Changes something, or Deletes something. That class uses the same policy as built-in tools.
  • Import from OpenAPI — paste a document or a URL, pick operations, set a base URL, import the selected ones.
  • Try it — a test call that never saves the response. Secrets show as ***.

Credentials stay on this server. The backend pins DNS, rejects a templated origin, caps streamed bodies (default 1 MB), and refuses plain HTTP unless an operator allows it. Tokens are never written into an export file.

Turn the flags on (operators)

All of these live under Operate → System configuration → Routing → Tools and approvals. Changes apply without a restart.

Setting Default What it does
TOOLS.REGISTRY_ENABLED on One tool registry. Off restores the previous per-loop catalogues (kill-switch).
TOOLS.APPROVALS_ENABLED off Approval cards, the Approvals inbox, and pause / resume on Saved Tasks.
TOOLS.CUSTOM_HTTP_ENABLED off Custom HTTP / OpenAPI tools on Connections.
TOOLS.POLICY.read auto Default for tools that only read.
TOOLS.POLICY.write approve Default for tools that change something.
TOOLS.POLICY.destructive block Default for tools that delete something.
TOOLS.APPROVAL_EXPIRY_HOURS 72 Hours a pending request waits (1–720).

auto / approve / block are the only policy values. Always allow is a per-user, per-assistant override and cannot turn a block into a run.

SQL if you prefer the database (group TOOLS, owner 0):

INSERT INTO BCONFIG (BOWNERID, BGROUP, BSETTING, BVALUE)
VALUES (0, 'TOOLS', 'APPROVALS_ENABLED', '1')
ON DUPLICATE KEY UPDATE BVALUE = '1';

INSERT INTO BCONFIG (BOWNERID, BGROUP, BSETTING, BVALUE)
VALUES (0, 'TOOLS', 'CUSTOM_HTTP_ENABLED', '1')
ON DUPLICATE KEY UPDATE BVALUE = '1';

Reload the app (or wait for the next runtime-config fetch). Rollback is the same statement with '0'.

What is not here yet

A step-list workflow builder and a webhook trigger are planned. They are not in the UI. Running arbitrary code on a compute node (sidecars/synaplan-compute) is in the repository as a sidecar image; PHP does not call it yet. See Architecture.

Related pages