What OrchKernel is

OrchKernel is the system a company runs its people and its AI agents on. It keeps one record of who works there, what each person and agent may do, the company's data, the work in progress and everything that happened. Agents do real work in it: they read records, draft emails, write updates, call the company's other systems. None of that happens around the kernel. Every step an agent takes goes through one checkpoint, the gate, which decides whether it may happen now, needs a person first, or is refused, and writes the decision to an append-only event log.

The short version, which the rest of this guide keeps coming back to:

Agents propose, humans approve, the kernel applies.

This page explains the ideas behind that sentence, follows one request from the moment someone asks an agent to the moment a record is written, and ends with the words the other pages use. It describes OrchKernel as it is today (version 0, the golive branch). OrchKernel is source-available under the Business Source License (BSL).

The ideas the rest of the guide relies on#

People and agents are both actors#

Everyone who can be given work is an actor. There are three kinds:

People and agents sit side by side in the Directory and the same threads. What differs is authority: an agent only ever acts for someone, with what that person gave it.

Tasks and runs#

A task is a piece of work: a title, who owns it, who it is assigned to, a priority and a budget. A run is one attempt by an agent at a task. Asking an agent, a schedule firing, a webhook arriving and a record changing all create a task first; nothing starts a run directly. That is what lets the kernel schedule, budget and account for every piece of work the same way.

A task moves through Open, Assigned and Running, and ends Done, Failed or Cancelled. In between it can be Parked: waiting for a person to approve something or answer a question. A parked run gives up its place and picks up from the exact step where it stopped once the person decides. A task that misses its deadline can be Escalated to a person, and stays open while it is.

A plan, where every step is a governed call#

An agent does not act directly. Its skill turns the task into a plan: a short list of typed steps, such as "read the open tickets", "write this lead", "call gmail.send with these arguments", "post a status in the thread". With a model configured, the model writes the plan; in the demo without a model key, a stub planner answers the walkthrough's asks with fixed plans. Some skills plan once; others work in rounds, planning a few steps, seeing their results, then planning the next. The kernel runs each step in turn, and every step that reads, writes or reaches outside is a syscall: a request to the kernel that passes through the gate before anything happens.

So an agent that has been talked into something it should not do still cannot do it. The plan is just a request. The gate decides.

Delegation only narrows#

An agent acts for a person because that person delegated to it: "the Sales Assistant may act for me on leads and contacts, may use gmail.send and calendar.create, up to 50.00 of spend". In the demo each module sets these up for you; Alice's delegation to the Sales Assistant, created by the crm module, is exactly that one. See Delegations.

Delegation has one rule that never bends: it only attenuates. An agent can never hold more than the person it acts for, and if it hands work on to another agent, that agent gets the same or less, never more. Revoking a delegation takes effect at once and also ends everything delegated onward from it. When someone is offboarded, all of it goes, and their running work is cancelled.

Risk lives on actions, trust lives on agents#

Every action has a risk tier, whoever does it:

Every agent has a trust tier, which caps how much risk it may take on without a person:

Company rules sit on top of both. A rule can hold an action for a named person or role whatever the trust tier. In the demo, a refund or goodwill credit by the Churn-risk watcher waits for an admin (rule: "Goodwill credits by agents over the cap of 100.00 in the account currency per call need an admin, whatever the trust tier"), and an email the Sales Assistant drafts waits for the rep it acts for (rule: "Agents never send email without the rep approving the draft"). See Policy.

The brain#

The brain is the company's data, in two halves:

• Collections of typed records: leads, tickets, customers, roadmap items. A collection either lives in OrchKernel or is kept in another system, such as Salesforce or Zendesk, and reached through a connection. Every record keeps who wrote it, which run, which skill and on whose behalf, and every change is a new version you can roll back to.
• Knowledge: facts, procedures and decisions written as text, each with a scope (private, team, company), a confidence and the evidence behind it. Knowledge an agent proposes for a team or the whole company is quarantined until a person accepts it.

Each person sees only the records and knowledge they may read, and so does every agent acting for them. See The brain and Knowledge and decisions.

Threads#

A thread is where people and agents work on one goal together: the conversation, the agents' runs, the documents being drafted, the approvals and the decisions all in one place. A conversation with a single agent is a private thread too. See Threads.

Packs, modules and blueprints#

What a company's agents can do comes in packs: a pack bundles collections, skills, agents, rules and pages for one area, such as crm or support-ops. A module is a pack a company has turned on from the Modules page, with its teams, connections and triggers set for that company. An admin can pause a module, which stops its agents, tools, triggers and pages at once and keeps its data. (Pausing support-ops in the demo removes Maya's Support operations page, and an ask to the Churn-risk watcher is refused with "support-ops is paused" until it is resumed.)

A blueprint describes a whole company or department (packs, teams, seats, who acts for whom) and sets it up in one step. See Modules and Setting up a company.

Agents propose, humans approve, the kernel applies#

This holds well beyond approval cards. Agents never change the rules they run under. A new field, a new page, a changed playbook, a new rule, a whole new department: an agent may draft each of them, but it arrives as a change that a person reviews, often after automatic tests (evals), before the kernel applies it. The built-in agents work this way: the Schema Steward proposes fields, the Designer proposes pages and the Architect proposes modules and blueprints.

Even the screens are data. Most pages under a module (Alice sees Leads, Pipeline and Sales desk under Sales) are records in a views collection, so a new page is a proposed record, versioned and rolled back like any other. The system pages (Inbox, Threads, Work, Governance, Directory, Events) ship with the product.

How a request flows#

These seven steps are the same whether a person asks in a thread, a schedule fires or a webhook lands. The example is Maya, the support lead, asking the Churn-risk watcher about ticket T-1042, where Northwind was charged twice and wants 250.00 back.

1. A task is created. Maya's message creates a task, owned by her and assigned to the Churn-risk watcher. The thread shows it under Tasks.
2. The task is scheduled. The scheduler starts it when the agent has room, by priority and the task's dependencies. Asking from a thread with Ask agent starts the run at once; an @ mention waits for the next tick of the server's clock, which runs every 30 seconds.
3. The agent plans. The runner picks the skill that fits ("Churn-risk watching"), works out who the agent acts for (Maya, through her delegation) and asks the model for a plan. This skill works in rounds: round 1 reads the ticket and looks up Northwind's account in billing, round 2 asks to refund 250.00.
4. Each step passes the gate. For every step the gate checks, in order: that the agent holds a delegation from the person it acts for, that no pause or kill switch (an admin's emergency stop for one agent, a tool, a team or every agent at once; pausing a module sets these for its agents and tools) stops it, that the agent is active, that the skill declared this tool or collection, that the delegation covers it, which model may see the data (for a model call), the budgets of the agent, task and thread, the company's and module's rules, and finally the risk against the agent's trust. Reading the ticket and the account passes. The refund meets the rule "Goodwill credits by agents over the cap of 100.00 in the account currency per call need an admin, whatever the trust tier". See How the gate decides.
5. An approval parks the run. The run stops before the refund and an approval card appears in Maya's conversation and in Ada's inbox with the exact amount, invoice and reason. Nothing has been refunded. When Ada approves, the kernel performs exactly that refund and the run carries on from the next step. If she rejects it, the run gets the rejection instead.
6. Everything lands in the event log. Each step, gate decision, approval, tool call and record write is appended to the log with who did it and for whom. The run can be replayed from the log afterwards. Two things a run does are not yet tied to it in the log; see Known problems.
7. The agent remembers. After a successful run the agent keeps a short private note of what it did, visible to the person it acted for (Maya) under Knowledge, Agent memory, for 90 days. Anything it wants the team or the company to know is proposed as knowledge and quarantined until a person accepts it.

Follow one request in the demo#

You need the demo company running (see Quickstart). With no model key, a stub planner answers this ask with a fixed plan; the gate, approvals and log are real either way. On a phone, the sidebar (with Sign out and every page) opens from the menu button at the top left.

1. Sign in with maya's token. Her workspace opens on Threads. Under Talk to an agent, click Churn-risk watcher. You see "New conversation with Churn-risk watcher".
2. Type Northwind wants a refund for the double charge and press Ask agent. You see your message, then a card Issue a refund or credit, Pending: Amount $250.00, Invoice inv-2026-09-1042, Reason "Double charge on the September invoice (ticket T-1042)", the rule "Goodwill credits by agents over the cap of 100.00 in the account currency per call need an admin, whatever the trust tier", and "Waiting for an admin (Ada Park)." The details panel on the right (Details on a phone) lists the task under Tasks as Parked. Maya has no Approve button.
3. Press Sign out and sign in as ada. Open Inbox. Under Waiting on you is the same card, with Why am I asked?, Reject and Approve.
4. Press Why am I asked? The gate's checks are listed one per line: Delegation held, Kill switch, Active, Skill, Delegation, three Budget lines (agent, task, thread), Rule, Approver. The Rule line reads "A Support operations rule requires approval" and the Approver line "Ada Park would be asked, and the run would wait until they decide".
5. Press Approve. Because money moves, the buttons change to Cancel and Approve $250.00. Press Approve $250.00. The card leaves the inbox, which now says "Nothing here."
6. Open Work, then the Runs (1) tab, and click the Churn-risk watcher run (state Done). The run panel says "Churn-risk watcher acting for Maya Patel" and the trace lists each step: Used the skill Churn-risk watching, Planned the next step, Read Tickets: 1 row, Billing account Ok, Round 1 · 2 operations, Planned the next step, Asked for approval, Approval Approved, Issue a refund or credit Ok, Round 2 · 1 operation, Planned the next step, and last Kept 1 lesson. The Output shows Refund re_3Rk0a1Lq. Replay (raw events) lists the run's entries from the log, from run_started to run_finished, including the policy_evaluated entry whose decision is require_approval.
7. Close the run panel, open Events and pick Policy decision in the Type list. Among the entries are "Churn-risk watcher: tool.call(support-ops.billing.refund) needs approval" and "Churn-risk watcher: brain.query(tickets) allowed". Pick Tool called and you see "support-ops.billing.refund called by Churn-risk watcher".
8. Sign in as maya again and open Knowledge, then Agent memory: the watcher's note "Finished 'Northwind wants a refund for the double charge' (Churn-risk watching) for Maya Patel." with the amount, invoice and refund id, "by Churn-risk watcher", expiring 90 days from today.

For the lower-risk side of the same flow, sign in as alice, click Sales Assistant under Talk to an agent, and ask Email a follow up to my contacted lead. A card Send email, Pending, shows the draft to dana@litware.example ("Following up on our demo"). It waits for Alice herself (rule: "Agents never send email without the rep approving the draft"), so she has the Approve button, and there is no second confirm because no money moves. When she approves, the demo mail fake answers msg-18c2f1a9 and the run finishes Done. The same run then writes the Litware lead, which Alice owns, to set its next follow-up date. That write needs no one: in the run's trace it is Wrote a leads record (version 2), the lead's provenance reads Sales Assistant acting for Alice, and under Events, type Record written, the entry reads "Leads ... written by Sales Assistant".

Ask the watcher for the same refund a second time and the gate refuses it: the trace shows Refused: policy denied Issue a refund or credit: Invoice inv-2026-09-1042 was already refunded (re_3Rk0a1Lq on 2026-10-05) (with your own date). With the stub planner the run still ends Done and its output still reads "Refunded after an admin approved it." with no refund id; see Known problems.

Not possible yet#

A few things the ideas above point at are not built yet:

• Rebuilding all state from the log alone. Runs can be replayed from the log, but the company's state is kept in a snapshot beside it, and some changes (budgets, closing a thread, policy changes) do not yet write enough to the log to rebuild from it.
• Fair-share team queues. Tasks are scheduled by priority, capacity and dependencies; sharing a team's capacity fairly between queues is designed but not used.
• A remote pack registry. Packs come bundled or are uploaded to a company's own catalog; there is no shared registry or signing yet.
• Notifications outside the product. Approvals reach people through the inbox and on-screen notices only, not email or chat.

Where each part is covered#

Glossary#

Known problems on this page#

• Asking the Churn-risk watcher for the T-1042 refund a second time: the gate correctly refuses the refund (the invoice was already refunded), but with the stub planner the run's output still reads "Refunded after an admin approved it." with an empty refund id, the run is marked Done, and the watcher keeps another Agent memory note for Maya from that run.
• When an agent proposes team or company knowledge, the Knowledge proposed event is not tied to the run, so filtering the Events page by that run, or replaying it, does not show the proposal, and the run's trace has no step for it.
• Asking an agent of a paused module over the API (POST /ask) is refused ("support-ops is paused"), but the task behind the ask is still created and left open. When the module is resumed, the next clock tick runs it, although the person was told the ask was refused.
• The private note an agent keeps after a run (the trace's Kept 1 lesson, shown under Knowledge, Agent memory) writes no event at all, so it appears in neither the Events page nor the run's replay.

For developers#

The ideas above map onto these parts of the code:

To watch the flow over the API (all routes under /api, with Authorization: Bearer <token>):

The design behind all of this is in docs/rfcs/0001-object-model.md and, for views, docs/rfcs/0002-views-as-data.md.