Inbox and approvals

Your inbox is where OrchKernel tells you about work that involves you: an agent that needs your approval, a question a run is waiting on, a mention in a thread, a task handed to you. An approval is the moment a person decides whether an agent may go ahead with something the company's policy holds for a person, such as a refund over the cap or an email to a customer. Until someone decides, the agent's run (one attempt by an agent at a task, with its steps; see Asking an agent) is parked: it stops and waits.

What is not possible yet is listed at the end.

What lands in your inbox#

Items from OrchKernel itself (updates, questions) show the OK badge and "OrchKernel" as the sender; the others show who sent them.

The Inbox link in the sidebar shows how many unread items you have, approvals waiting on you included.

Unread and Everything#

The Inbox page has two tabs.

• Unread (the default) lists items you have not read yet. Approvals are not repeated in this list: the ones you decide appear as full cards under Waiting on you at the top. When there is nothing, it says "Nothing here."
• Everything lists every item you ever received, read or not, newest first. Approvals appear here as one line with where they stand, for example Issue a refund or credit: approved with an Approved badge, or Issue a refund or credit: rejected with Rejected.

Marking items read#

An unread item has a dot at its right. Press the dot to mark it read. An item that opens nothing (such as "removed you from a thread", a Completed note or a question) is marked read when you click it.

Some items are marked read for you:

• an approval, once you decide it;
• a question, once it is answered.

Opening an item that leads somewhere (a mention, for example) does not mark it read.

Pressing the dot has no visible effect: the row and the sidebar count stay the same until you reload the page. The item is marked read; after a reload it is gone from Unread and the count is one lower. This is a known bug.

Waiting on you and Waiting on others#

Above the items list, the Inbox shows pending approvals as cards:

An admin sees every pending approval in the company, so Ada's Waiting on others holds, for example, the follow-up email that only Alice may approve. Anyone else sees only the approvals addressed to them. An approval in your own conversation that someone else decides (such as Maya's refund, which waits for Ada) shows on the conversation, not in your inbox.

Governance › Approvals lists the same pending approvals as cards, without the other inbox items. When there are none it says "No pending approvals."

The approval card#

The same card appears in the inbox, on Governance › Approvals and in the conversation where the agent was asked. For the demo refund it reads:

Issue a refund or credit · Pending Churn-risk watcher asks to issue a refund or credit on behalf of Maya Patel. Amount $250.00 · Invoice inv-2026-09-1042 · Reason Double charge on the September invoice (ticket T-1042) Goodwill credits by agents over the cap of 100.00 in the account currency per call need an admin, whatever the trust tier · See the run · 4:58 PM

After a decision the card says who decided and when: "Approved by Ada Park · 5:00 PM", or "Rejected by Ada Park · 4:59 PM: Billing is already refunding this by hand".

Who may decide#

Only a person can decide. Being an admin is not enough on its own: Ada sees Alice's email card but cannot approve it (the API answers 403 ada may not decide approval ...). Who is asked comes from the company's policy, not from the thread; see Policy, rules and kill switches.

The agent's manager has no place in the workspace to decide: the approval is not in their inbox, and they cannot open the person's conversation. Sam can decide Alice's email only through the API (below).

Who can see an approval: admins, the agent that asked, the approver, the person the agent acts for, anyone who may decide it, and anyone who can see its run, task or thread. To anyone else it does not exist (the API answers 404).

What happens when you approve#

1. A confirmation, for money. For a refund or other financial action, Approve first shows "Issue a refund or credit of $250.00? It runs as soon as you approve." with Cancel and Approve $250.00. Other actions, such as an email, are approved with one click.
2. The re-check. Before anything runs, OrchKernel checks again:
   • the approval is still pending and you may decide it;
   • neither the agent nor the tool is paused (a paused module counts);
   • what the policy says now. If a rule now refuses the action, approving is refused and the approval stays pending so it can be rejected. If the policy now asks someone else, only that person may approve.
3. The action runs. That one action is carried out, exactly as the payload shows. The toast says Approved.
4. The run resumes from the next step. The agent does not start over: it carries on with the rest of its plan from where it parked. The ticket and the account it read before the approval are not read again.
5. The result lands where it was asked. In the demo, Maya's conversation shows "Refunded after an admin approved it." with the refund id re_3Rk0a1Lq, and Maya gets a Completed update in her inbox.

While a module is paused (see Modules), its approvals stay pending. The card shows a Module paused badge, the line "CRM is paused. This waits until an admin resumes the module; then it can be approved. You can still reject it.", and, next to a greyed-out Approve, "Approve is off while CRM is paused."

What happens when you reject#

Reject opens a reason box. For a financial action the box is labeled "Reason (required)" and Confirm reject stays greyed out until you write one; otherwise the reason is optional.

• The action never runs. The toast says who hears of it: "Issue a refund or credit: rejected · Maya Patel was told".
• The run stops. In the conversation its result reads "Rejected by Ada Park ... What the run did before the rejection is under Details." with a Declined badge, and its task shows Cancelled.
• The person the agent acted for gets an inbox update: "Declined 'Northwind wants a refund for the double charge': Ada Park rejected "Issue a refund or credit": Billing is already refunding this by hand".

A decision is final. Deciding an approval that is already decided changes nothing.

Expiry#

Approvals asked by OrchKernel's own agents do not expire: the run waits until someone decides. An outside agent's approval expires after that agent's approval time (24 hours unless an admin set another); its card shows "Expires in ..." and, afterwards, "nobody decided it in time, so the action did not run." See Outside agents.

Questions a run waits on#

When an agent needs something from a person before it can go on (a choice, a missing detail), it asks a question and the run parks. The question goes to the person the run acts for, and lands in their inbox ("Support Agent asks: Which invoice should I look at?") and in the run's thread, with any suggested answers ("Options: September, August"). A run may ask at most three questions.

The demo's stub planner never asks a question; you need a real model (see Models) to see one.

Today the web workspace cannot answer a question: the inbox row opens nothing (and a click marks it read although it is not answered), and the thread shows the question with no reply box. Answer with ok answer or the API (see For developers); the run then resumes with your answer, and the question is marked read. This is a known bug.

Try it in the demo: refuse, then approve the refund#

This uses the demo company from the Quickstart. With no model key, the demo's stub planner plans the refund; a real model plans its own steps, but the approval works the same way.

Start with a fresh demo (ok demo --force, then ok demo serve), so ticket T-1042 has not been refunded yet. The workspace is at http://127.0.0.1:8080 unless you started the server with another --bind.

Ask for the refund#

1. Sign in as maya (support lead). Click Threads, then Churn-risk watcher under Talk to an agent. Type Northwind wants a refund for the double charge and press Ask agent.
2. The conversation shows the approval card Issue a refund or credit, Pending, for $250.00 against inv-2026-09-1042. Maya is the person the agent acts for, but there is no Approve button: the card says "Waiting for an admin (Ada Park)." In the side column, Tasks shows the task as Parked.
3. Maya's own Inbox says "Nothing here.", and Governance › Approvals says "No pending approvals.": the refund is not hers to decide.

See a wrong person refused#

The screen hides the buttons from anyone who may not decide, and the server refuses them too. You need the approval's id: it is the id in Ada's list of pending approvals.

curl -H "Authorization: Bearer <ada's token>" \
  http://127.0.0.1:8080/api/approvals

Then try to approve with Maya's token:

curl -X POST -H "Authorization: Bearer <maya's token>" \
  -H 'content-type: application/json' -d '{"approved": true}' \
  http://127.0.0.1:8080/api/approvals/<approval id>

It answers 403 {"error":"not_approver","message":"maya may not decide approval <id>"}. Tom, Alice or Fiona, who cannot see the approval at all, get 404 not_found. Rejecting ({"approved": false}) is refused the same way.

Refuse it#

4. Sign out and sign in as ada (admin). The sidebar's Inbox shows 1.
5. Click Inbox. Under Waiting on you is the refund card. Open Why am I asked? to see the checks, ending with "The policy asks anyone with the admin role."
6. Press Reject. Type a reason in Reason (required), such as Billing is already refunding this by hand, and press Confirm reject. The toast says "Issue a refund or credit: rejected · Maya Patel was told".
7. Waiting on you is gone. Sign in as maya: the conversation shows the card Rejected with "Rejected by Ada Park", the watcher's result with Declined, and the task Cancelled. Maya's sidebar Inbox shows 1: the Declined update. No refund was made.

Approve it#

8. As maya, in the same conversation, ask again: Northwind wants a refund for the double charge. A new card appears, Pending, waiting for Ada.
9. As ada, open Inbox, press Approve on the refund card, then Approve $250.00. The toast says Approved and Waiting on you is gone. Under Everything, the item now reads Issue a refund or credit: approved with an Approved badge.
10. As maya, open the conversation. The card says "Approved by Ada Park", and below it the watcher's result: "Refunded after an admin approved it.", amount $250.00, invoice inv-2026-09-1042, refund re_3Rk0a1Lq, Done. Maya's inbox has a Completed update.

Confirm the run resumed#

11. On the approved card, press See the run. A Run panel opens beside the conversation. Its Trace lists, in order: Read data (Read Tickets: 1 row), Tool (Billing account Ok), Approval (Asked for approval), Decision (Approval Approved), Tool (Issue a refund or credit Ok), and the model and round steps around them. The ticket and the billing account were read once, before the approval; nothing before the approval ran twice.

Asking for the same refund a third time is refused before anyone is asked. In the run's Trace, a Refused step reads "Refused: policy denied Issue a refund or credit: Invoice inv-2026-09-1042 was already refunded (re_3Rk0a1Lq on ...)" ("already has a refund waiting for approval" while one is pending). With the stub planner the conversation still says "Refunded after an admin approved it." and Done, with no refund id, which is wrong: no refund was made. This is a known bug in the demo's stub planner.

The email approval: one click, and who else may decide#

1. Sign in as alice (sales rep). Click Threads, then Sales Assistant. Ask Email a follow up to my contacted lead.
2. The card Send email, Pending, shows the recipient dana@litware.example, the subject "Following up on our demo" and the full text, with Approve and Reject. It is also in Alice's inbox under Waiting on you.
3. As ada, open Inbox. Waiting on others 1 is folded; click it. The card says "Waiting for Alice Chen." and has no buttons.
4. As alice, press Approve. There is no confirmation. The toast says Approved; the conversation shows "Approved by Alice Chen" and the result with Sent msg-... and Done.

Sam, who leads Sales, may also decide Alice's emails, but only through the API. Ask once more as Alice, then, with Sam's token and the new approval's id:

curl -X POST -H "Authorization: Bearer <sam's token>" \
  -H 'content-type: application/json' \
  -d '{"approved": false, "note": "Not this week"}' \
  http://127.0.0.1:8080/api/approvals/<approval id>

The approval comes back with "state": "rejected" and "decided_by": "sam", and Alice gets "Declined 'Email a follow up to my contacted lead': Sam Ortiz rejected "Send email": Not this week".

Not possible yet#

• Answering a run's question from the web workspace (use ok answer or the API).
• Seeing the effect of the Mark read dot without reloading the page.
• An agent's manager, who may decide an approval addressed to someone else, finding it in their inbox or deciding it in the workspace: only the API works.
• Delegating or reassigning a single approval to another person.
• Changing a decision once made.
• Opening a Change proposed review item on the Changes tab: it opens Governance › Schema; go to Changes from there.
• A time limit on approvals asked by OrchKernel's own agents.

For developers#

API#

All under /api, with Authorization: Bearer <token>.

Errors from POST /approvals/:id:

Events#

See Events and the audit log.

CLI#

The CLI opens the state file directly, so stop the server first (on the demo, --state orchkernel-demo/state.db). Without a model key, each command first prints a "warning: no model provider is configured" line.

ok --state <state.db> --as ada inbox          # unread items: * title  item-id
ok --state <state.db> --as ada inbox --all    # every item
ok --state <state.db> --as ada approve <approval-id>
ok --state <state.db> --as alice approve <approval-id> --reject --note "Not this week"
ok --state <state.db> --as maya answer <run-id> "September"

ok inbox prints item ids such as approval:4474d1d0-...; pass ok approve only the part after approval:, or it answers "Error: approval approval:... not found". ok approve prints the decided approval as JSON. A wrong person gets Error: maya may not decide approval <id> and exit status 1. Approving from the CLI runs the action from the CLI process, so on the demo, where the tools are local fakes started by ok demo serve, approve from the workspace or the API instead and use the CLI to reject.