OMNISLASH Omnislash — the self-evolving operator for your company

infrastructure

the substrate it lives on, deploys as, and is watched through

• Brain ↔ Engine Separation i The engine owns runtime — execution, queues, schema, CLI, Docker, monitoring. You own behaviour — prompts, roles, scenarios, skills, your own tables — as files in your own git repo, so every change to how the operation behaves is a diff you can review and revert, not a row in a vendor’s database. One typed config file is the entire contract between them, validated before the runtime boots. defineProject() — one file, no codegen, no generated directoryyour Zod env schema merged into the engine’s at loadtyped extension points: tools, integrations, ingest, engagement, dispatch, lifecyclefixed directories are convention, not configurationfail-fast validation with an actionable hint, not a stack trace docs/eaaf-criteria.md
• Agent-Run Upgrades i An engine upgrade is one command and one agent’s task. The command moves the pin, regenerates the files the engine owns and writes upgrade/TASK.md; a coding agent works that task to the end — names your files still spell the old way, read-only checks against production before the deploy, data fixes after it. Every release that needs something of your brain ships the prompt for it, and nothing upgrades a brain from CI. one entry per change, in order, across every release you crossbefore-deploy, in-repo and after-deploy steps — each detected, applied, verifiedthe deploy’s first gate fails while a step that must ship first is untickedstop-the-world deploys: old and new never run side by side, so a release ships its final shapeengine migrations applied by the deploy; each entry says what they need from your brainidempotent — fix the cause and re-run the command it hints docs/brain-dev/upgrading.md
• Durable Execution i Every agent is a Restate virtual object keyed by its id; workflow runs, planners, the eval service and your own pipelines are durable handlers. Kill the process mid-run, redeploy, lose the network — the same invocation resumes where it stopped, including across a human pause of days or weeks — no timeout ends the wait, and it costs zero compute while it lasts. one durable owner per agent id — the per-agent queue is nativethe human pause holds inside the same invocationjournaled steps, replay-safe, exactly-once terminalsthe database row is a projection, never the control surfaceorphans reconciled against Restate’s own tables, not guessed proven against real Restate in the engine’s integration suite
• Brain-Sync Daemon i One long-running service owns your brain’s git state, so no application process ever races another over a checkout. On a fixed interval it commits what the agents wrote, rebases, pushes, and refreshes the baseline that per-run sandboxes branch from. Nothing else boots until the first sync lands. a sparse checkout of exactly the writable set, and nothing elsecommit before pull, deliberately — agent work is committed, never stashedevery brain-consuming service gated on the first successful ticka rebase conflict spawns a resolver agent and holds all git until it verifies cleansync now from chat, from the dashboard, or from a push webhook docs/brain-dev/operations.md
• MCP Server i One HTTP process serves the whole tool catalogue to every agent, whatever it runs under — Claude Code, Codex, OpenCode or an API model. Each turn opens a session carrying the caller’s own identity, so the same tool name resolves to a different permission set depending on who is asking, and a harness can never call a name it was never shown. Streamable HTTP on /mcp, plus stdio for desktop clientsper-session catalogue filtering, re-checked at call timeprogress and cancellation notificationsread-only resources by URI (skills, own pending cards)idle session reaper, body and session capsloopback bind + origin allowlist against DNS rebinding docs/mcp.md
• Multi-Repository Operations i Your agents work across every repo you own, not just the brain. A scenario names its target; each run gets its own clone of that repo whose origin is the real upstream, so a branch and a push land where you expect. Skills are handed over as absolute paths rather than copied in, so git status in someone else’s checkout stays clean. a JSON name → git-url map, cloned on deployper-run sandbox per repo, same path in Docker and local devwrite-back and an engine-opened PR from inside the runskills delivered out-of-tree so the checkout is never dirtiedevery resolved repo path validated before anything boots docs/extra-repos.md
• Agent Sandboxing i Three blast radii, declared per agent: the live brain, its own git clone off a read-only baseline — independent index, HEAD and stash, sharing objects and nothing else, origin rewritten to your real upstream so a push lands — or a full bubblewrap jail that refuses to start if it cannot actually jail. runIn: live | clone | sandbox, declared in frontmatterper-scope checkouts sharing objects through git alternatesmount, PID and IPC namespaces, dying with the parentsame absolute paths inside and outside the jailpath containment on every file operationa database search path that hides engine tables from agent SQL docs/agent-isolation.md
• Unified Docker Image i bot · worker · scheduler · monitoring · mcp · webhooks · pipelines · dashboard · sync all route off one entrypoint. One image to build, one to pull, one to roll back — and your brain extends it with a two-line Dockerfile that joins the engine’s workspace, so there is exactly one physical copy of every package. entrypoint command routing, dumb-init as PID 1FROM ghcr.io/omnislash-ai/engine:X.Y.Z + your own layerthree CLI harnesses and their sandbox shims baked inskill install specs baked and verified at build timecompose generated per mode, with an override file when you need one docs/distribution.md
• BYOI — Bring Your Own Infra i Point the database URL at RDS, Neon or Supabase and the generated compose drops its own Postgres container, its exporter and its backup sidecar. Same for Redis. Nothing about the code changes; the deployment simply stops carrying what you already pay for. external infrastructure detected from env, not toggled by a flagcompose, exporters and probes all derived from that detectiona tuned Postgres 17.9 when you would rather not run oneone image and one CLI either way
• Monitoring & Auto-Remediation i Grafana, Prometheus, Loki, Sentry and a queue inspector, provisioned as code rather than clicked together — nine dashboards and forty alert rules up on the first deploy. And an alert does not only page you: it POSTs back in as an ordinary external event, where a hook wakes an agent that chooses between an idempotent fix, a pull request, or escalating to a person. nine dashboards and forty rules as code, routed to chatblackbox probes and per-container restart detectionthe firing alert re-enters through the engine’s own event doora disaster-recovery skill on the remediation pathlogs as JSON into Loki, run and agent ids as metadata rather than labels docs/observability.md
• External Event Ingest i Anything that can POST becomes a trigger. You declare the source; the engine gives it an endpoint, authorizes it and records it in one durable inbox — and only that recorded row sets work in motion, so your hooks fire once per event however often a job is retried. There is no provider-specific code anywhere in the engine. defineEventSource with your own extract(), returning null to refusethe endpoint provisioned for you, per sourcededup by persisting — one upsert decides new, revived or duplicatean accepted event cannot be lost: a row nothing routed is re-routed within minutesper-source secrets, several of them, each revocable on its ownthe ingest log and a generated event-schema catalogue in the dashboard docs/webhooks.md
• Integration Kit i You describe an integration once — its auth, its webhooks, its tools — and the engine registers it everywhere: MCP, worker, pipelines, chat. No per-integration boilerplate. OAuth connections live in one encrypted store that refreshes tokens in the background, so a long-running agent never wakes up logged out. defineIntegration — tools and webhooks in one validated objectregistration fan-out to every surface that builds a registryper-subject connection store, AES-256-GCM at the columnbackground refresh and best-effort upstream revokeOAuth that completes on a server with no inbound port open docs/integrations.md
• Webhooks Service i One HTTP door into the running brain, and everything behind it is already wired: run a tool by name, fire a workflow, take an inbound event, finish an OAuth callback, serve a published artifact. Raw bodies are captured before parsing, so an HMAC signature verifies real bytes rather than re-serialized JSON. POST /tool/:name under a headless context — HITL tools unreachable by constructionPOST /event/:source for ingestyour integration routes, authorized by your own signature checkOAuth init, callback and statusthe published-artifact origin with ETag and a CSP sandboxthe endpoint catalogue rendered in the dashboard docs/webhooks.md
• Event-Driven Hooks i A markdown file names an event and an agent; the engine does the rest. One subscription covers the whole closed event set, so a hook added or edited while the system runs fires at its next matching event with no restart. N worker replicas collapse onto one keyed job, so it fires once, not once per replica. one file: event, agent, prompt — no subscription code anywhereexactly-once across replicas, with retries and a dead-letter queuehot reload behind a bounded probea hook naming an impossible event is caught at boot, not at 3amper-fire declared grants with a real call ceilingrun-scoped hooks that live and die with one workflow run docs/events-system.md
• Artifacts Store i Everything a run produces is a file in one declared tree: outputs handed between phases, files sent back to chat, the bytes behind a published link. Each subtree names its own lifecycle, so the retention sweeper is derived from that one table and a new subtree cannot quietly escape it. content-addressed blob store behind one routerrun artifacts as file-based context passing — manifest in, pull what you needper-task stored artifacts that outlive the run directorylarge step payloads offloaded to blobs instead of a rowTTL and size-budget reaper, oldest-firstin-chat file and folder browser with drill-down docs/artifacts.md
• Attachments Pipeline i A photo, a voice note or a document arrives in chat and reaches the agent as a real file — one representation carried unchanged from the ingress, through the tool results, into both agent boundaries, and rebuilt into the conversation history on every later turn. The message text stays exactly what the person typed. one persistence type across every ingress, transport shape stops at the doorvoice replaces text rather than duplicating itan album arriving as N updates folded into one turnthe URL resolved at the door, so no lazy resolver leaks into the domainsending a file back blocks until it actually landed docs/attachments.md
• BullMQ Orchestration i Sixteen named queues are the at-least-once substrate under everything that is not a durable handler: planning, notifications, evaluation, improvement, heartbeats, hook fires, memory operations, delivery. Job ids are derived from the event itself, so replicas collapse onto one job and retries and a dead-letter queue come free. deterministic keyed job ids derived from the payloadper-domain retry chains — eval backs off past its own leaserepeatable crons reconciled by diff, never nuke-and-pavedelayed jobs behind scheduling, snoozes and boss expirya queue inspector and depth metrics on the first deploygraceful drain with a cancellation signal into live git and agent work
• Brain-Owned Database i Your tables are first-class, not "just the public schema". Two ordered, versioned migration lines run on every deploy — the engine’s own schema first, yours second, each with its own journal — so an engine upgrade and your own schema change never fight over one history. engine in its own schema, yours in public, composed by importthe table is the only source of types — rows and params derive from itgenerate / migrate / status; push never runs on an automatic pathconcurrent-index migrations with invalid-index cleanup on failurea dump sidecar with day/week/month rotation and its own probe docs/migrations.md
• Zero-Config Dev Infra i One command and the substrate is up: Postgres, Redis, Prometheus and the durable runtime in containers, migrations applied by the same code path production uses, then every service started as a watched child process you can attach a debugger to. Nothing to install and nothing to wire — and the first Ctrl-C takes the containers down with it rather than orphaning them. infra in Docker, apps as watched processes with the inspector availablemigrations run through the production runner, never a dev shortcutboot a slice of the system when you only need a slicea per-app readiness gate, so one slow service never blocks the othersshutdown waits for the children, then stops compose exactly once docs/run-modes.md
• Doctor Check Library i One check library, two consumers: about forty-five checks from the CLI before you deploy, two dozen container-safe ones inside the running dashboard afterwards. Every check is wrapped and deadlined by construction, so a wedged Docker daemon or an unreachable server produces a named failure instead of a hung terminal. environment, configuration and infrastructure, every check self-describinga throw becomes a correctly-named failure; ten seconds is the ceilingyour writable paths, declared grants, eval ceilings and skill binaries all checkedevery warning carries its remedy, and one tap hands it to an agent that applies itthe dashboard set and the diagnostic tool derive from one sourceunpersistable and merely degraded are different verdicts, not one warning docs/doctor.md
• Agent-Readable Logs & Config i An agent asked why something broke reads what you would read: the container logs Loki holds — by service, level, run or agent id and a literal search —, the events as they crossed the bus, and the configuration as the engine runs it, every value with the tier that set it. A secret answers by its presence alone, and its value is scrubbed out of every string the answer carries. retention said out loud — a window older than Loki keeps reads empty, not quietpolled, not followed: ask again from where the last page endedevery MANIFEST key marked as the engine’s default or your brain’severy declared environment variable, with whether it is setthe event tail refused to a turn answering one chat, because it carries every chat docs/brain-dev/features.md
• Typed Event Bus i 104 typed events across 20 domains, each one a schema in the engine’s registry, validated where it is emitted and again where it is received. Two substrates behind one vocabulary: pub/sub for the real-time surfaces, Redis Streams with consumer groups for anything that must not miss a message. payload types derive from the schema — no hand-written event interfacespub/sub or streams, chosen per consumer rather than per eventrequest-response over pub/sub, so cross-process calls need no second channelwildcard subscriptions with typed matching, not string sniffinga brain declares its own events through the same contract docs/events-system.md
• Resource Watches i An agent that opened a pull request does not poll it. It watches the PR, and the reviews, comments, settled CI, a new conflict and the merge arrive in its inbox as batched turns — a review with six inline comments is one turn, not seven. Its own acts come back as echoes and are dropped, CI about a commit a push already replaced is dropped, and a pipeline waits on the same resource durably instead of holding an agent open. one watch per agent and resource; watching again renews itone batch per burst — debounced, and never later than its longest waittrusted authors by default; every dropped event ledgered with its reasonit ends only in a delivery: the terminal event, the expiry or the budget, said out loudthe claim and the inbox entry commit together, so a retry never delivers twiceyour own event sources key their events; pipelines wait through subscribeResource docs/brain-dev/features.md § Resource Watches
• Deploy-Owned GitHub App i The engine holds its own git identity instead of borrowing the host’s SSH key: an agent posts one card, a person clicks through GitHub’s registration and install screens, and every repo resolves to a lane the agent can name. The same App is the receiver for every PR, review, check and push — and because GitHub never retries a failed delivery, the engine reads the App’s own delivery log and pulls back whatever it missed. registered through GitHub’s manifest flow, from one agent card or the dashboardwhich credential authenticates each repo, and why, answerable by an agentone signed receiver for the whole event family, verified over the raw bodymissed deliveries recovered from GitHub’s own three-day logsignals GitHub never sends: every check settled, a PR that began or stopped conflictingsubscription drift reported by doctor, not discovered by a silent agent docs/brain-dev/integrations.md
• Domain Mode with Auto-TLS i Set a domain and an email and the proxy becomes a Let’s Encrypt terminator with a subdomain per service — bot, dashboard, grafana, webhooks, artifacts. Certificates persist across recreates, admin vhosts sit behind basic auth, and the public URLs other features need are derived from the domain instead of being declared a second time. nine service subdomains routed from one variablecertificates in their own volume, so a redeploy does not re-issueadmin vhosts and private published artifacts behind the same credential pairwebhook and artifact origins derived, so OAuth installs need no second variablea self-signed fallback for a server that has no domain at all docs/production.md
• Volume Architecture i One named volume per durability class, and the classes are the design. The brain’s git state is mounted whole only by the sync daemon — every other service sees per-path subpath views, so no application container can reach the .git directory it might corrupt. git state exposed to services as subpaths, never as a repositorya read-only baseline clone as the object source for per-run checkoutsrun sandboxes surviving restarts, so a paused run can still resumethe artifacts root a sibling of the brain, so a sandbox mount cannot shadow itdumps, certificates and log positions each in their own volume docs/distribution.md
• G / R / W Path Classification i Every path under the brain is exactly one of three things: git-backed and writable, image-baked and read-only, or host-bound runtime output. That one classification drives the sparse checkout, the daemon’s commit set, the container mounts and the ignore file — so "will this write survive a container recreate" is a design-time question with an answer, not a 3am discovery. one resolver feeds checkout anchors, mounts, commit set and ignore fileadditive only — a brain extends the writable set, never shrinks the baselinestructural and blast-radius paths refused where you declare themdirectories only, because the checkout anchor never matches a filenew files inside the set are hot; a new dependency still needs a build docs/runtime/contract.md
• Stable Error Codes i Every failure the engine can produce carries a machine-readable code and a hint naming the next action — one taxonomy across the CLI and config layer, a typed family across the runtime. A brain author reads a code and a sentence, not a stack trace from inside a package they did not write. code, hint and a JSON form on every error the engine throwstyped families for agent, tool, service, auth and database failuresconfig validation fails before boot, with the offending field namedthe same codes reach the dashboard, not only the logs
• Graceful Shutdown & Signals i One shutdown path for every app: a signal drains in-flight work through the same cancellation primitive the rest of the runtime uses, so a deploy never severs a git push mid-write or leaves an agent subprocess orphaned. A watch-mode restart is told apart from an admin’s stop, because they deserve different behaviour. one registration call gives any app the whole contractthe abort signal reaches live git and agent work, not just the HTTP servera hot-reload signal is not mistaken for a shutdowninfrastructure teardown runs exactly once, in a finally
• Pipeline SDK i The helper surface your pipeline code writes against: run an agent, block on a human approval, ask a question, call any tool through the full gateway, keep state between invocations, report progress. Every helper is journaled, so all of it replays correctly after a crash — with an escape hatch to the raw runtime for anything not yet wrapped. runAgent with a Zod schema — the answer comes back parsed and typed, or as a typed failurerunWorkflow — a planned scenario as one durable step, idempotent on its keyawaitApproval holds the handler open, under a deadline your brain sets — a week by defaultcallTool goes through authorization, rate limiting and risk-based approvala Postgres-backed key-value with a TTL, for state across invocationsprogress that lands on the live card without polluting the step log docs/restate-pipelines.md
• Media Processing i Media that arrives is understood, not just stored: magic-byte type detection that outranks both the extension and what the sender claimed, image resize and conversion, PDF text extraction that falls back to rendering the pages for the model when a document turns out to be scanned, and transcription across a provider chain that fails over on its own. sniffed type wins over the extension and over the declared onea transcription chain of three providers, each enabled by its own keytranscripts cached by the file’s platform identity — first write winsone document reader: PDF, Word, Excel, slides, OpenDocument, EPUB and HTML, as markdownevery remote fetch DNS-pinned per redirect hop and capped mid-streamper-kind byte caps, with a local path allowed past the chat platform’s own limit docs/media.md
• Images for the Model i A tool can answer with pictures meant for the agent that called it, not for the person in the chat: a scanned PDF too thin to read as text arrives as its rendered pages, a widget preview as screenshots. An API agent reads them as image parts of the tool result, a CLI agent as MCP image blocks — and no transcript, journal or event ever stores the bytes. declared per tool; the result still says in words what the images showat most ten images a call, 5 MB each and 20 MB togethera provider that takes no image in a tool result gets a one-line note instead, per chain steponly an agent’s call carries them — a pipeline or a page gets the result withouta newer image under the same key supersedes the older one within the turnscanned pages past the first ten named, and read on the next call by page number docs/brain-dev/features.md
• Brain Scaffolding i One command emits a standalone brain — chat-only, scheduled-ops or pipeline-heavy — already pinned to the registry and installable on its own. A drift test keeps what it generates byte-identical to the fixture the engine itself develops against, so a new brain never starts life as a stale copy of someone’s working tree. three flavors, each a working project rather than an empty folderregistry-pinned peers, so the singleton contract holds from minute onethe Dockerfile and deploy workflow are engine-owned and regenerate on upgradean override sentinel per generated file, when you do want to own it
• Distributed Rate Limiting i One limiter in Redis, shared by every process — bot, worker, MCP and pipelines draw from the same budget instead of each keeping a private counter. Per-minute and per-day windows are checked and incremented in a single atomic script, so two containers cannot both squeeze through the last remaining call. one script per decision, returning which window was actually exceededthe metric label and the counter key are separate, so per-id limits never explode the metricsa read-only inspector over the live countersrejection arrives as a typed error the caller can branch on
• Distributed Circuit Breaker i One process discovering a dead provider trips the breaker for every container at once. Closed opens after three failures, half-opens after a cooldown, and expires on its own if nothing touches it again — all in atomic Redis scripts, so there is no window where half the fleet still hammers an endpoint the other half has given up on. closed → open → half-open, with the state shared rather than per-processa state-change callback, so a trip is announced instead of inferredper-provider state readable live, and rejections countedkeys expire by themselves — a forgotten breaker cannot wedge a provider forever

intelligence

what it thinks with, reaches for, and learns from

• Improvement Loop i The engine improves what it runs — workflow and pipeline scenarios, heartbeats, chat roles — and every change is a pull request against your own repo, never a push. A pattern in the graded window opens a cycle: an analyst proposes one change to the thing that ran, a separate implementer writes it, and the engine commits only the files that passed its diff gate. One live change per target at a time. Every settled verdict is filed as a lesson the next analysis has to cite, credited or charged by what happened. repair opens on k bad runs out of n; evolve runs on a cadence even when nothing is wrongthe editing agent holds no git credential and no shell — the engine commits and opens the PRit touches only the files the accepted proposal names, its own pipeline code includeda lesson per verdict: hypothesis, files, metric deltas, and your note if you rejected itevery settled cycle graded: improvement, regression, tradeoff, tie or inconclusivea spend bound per cycle, a cooldown after a regression, a daily cap on analyses docs/brain-dev/self-evolving.md
• Pre-Merge A/B Replay i Before a workflow change can merge, the engine replays the candidate from the PR head and the incumbent from the base commit on the same frozen past inputs — partly held out from the agent that proposed it — and compares them input by input under the same judge. The verdict is an ordered rule over your metrics, posted as a commit status on the exact commit it checked, so a branch rule can require it. A candidate that loses closes its own PR: nothing shipped, nothing to revert. paired, not batch against batch — two batches on different inputs measure the inputsthe failure being fixed is always in the set; the rest are held out from the proposer firstreplays act on nothing: a tool that would touch the world is authorized, then not performeda crashed candidate counts as the change failing, never as a missing data pointwhen you require a gain, it has to clear a noise band to count as onefor workflow scenarios with a replayable plan; everything else is watched after merge docs/brain-dev/self-evolving.md § What the check does
• Post-Ship Watch & Revert PR i Every change is watched after it lands, on the entity’s own next graded runs, counted from when it went live rather than when the PR opened. It settles validated, regressed or unvalidated, and unvalidated stays an honest terminal: “not checked” never becomes “checked and fine”. A regression opens a mechanical revert PR through the same gate the change shipped under, and the entity opens no new cycle until that revert settles. A heartbeat is never forced to run just to score itself — that would send real messages. every verdict labelled by its strength: paired, measured or blinda watch that sees a sibling’s change or a hand edit closes confounded — no credit, no revertlock groups: one variable at a time across entities that share an outcomean unproven change can be reverted too, if you say sothe revert PR is merged by a person unless you let changes auto-mergeduring the watch the target skips sampling, so no run goes unread docs/brain-dev/self-evolving.md
• Measurement Wall i The agent that rewrites a prompt cannot read the rubric it will be graded by, and cannot edit the judge, its model, the loop’s own code, its tolerances or its own autonomy — not even those blocks inside the very file it is allowed to rewrite. Enforced in the harness’s permissions, in the sandbox where one runs, and by a digest-pinned diff gate after the turn, so a violation never becomes a PR. The judge is frozen for the whole cycle: a grade from a moved judge is not comparable, never a loss. a floor a brain can add to and never shrink: eval methods, loop code, models, memory, deploy filesthe measurement blocks deep-compared before and after the editone change capped at 600 lines, counted off the real diff — no prompt bloatthe judge pinned by a four-part fingerprint for the whole cycletoo many ungraded runs settle “judge unhealthy” — nothing is reverted on a broken instrumentsymlinks, git hooks and engine-skill shadowing refused at the gate docs/brain-dev/self-evolving.md § What the loop may not touch
• Business-Metric Objectives i You decide what “better” means. An entity declares named metrics — each an objective, a guard or only observed — with floors, tolerances and per-input vetoes, and a metric can be read by your own code from the business rather than from the transcript. When the outcome only exists later, a video’s views at 72 hours or a delivery rate that settles overnight, the judge waits that long before it grades. Once anything else is the objective, quality becomes a guard on its own, so the loop cannot buy a number by getting worse. objective, guard or observe — a guard past its band vetoes before any score is reada critical metric vetoes on a single inputmeasure() in your own code: a CRM, a warehouse, an analytics APIgrading delayed until the outcome exists, per entityup to six business KPIs on the overview, readable by agents tooa metric edited mid-cycle is a judge change, never a silent rescore docs/brain-dev/self-evolving.md · docs/brain-dev/kpis.md
• Earned Autonomy & Breaker i Two gates, declared apart: who accepts a proposal and who merges the PR — each a person or the engine, a person by default. An automatic merge means arming GitHub’s own auto-merge on the commit that was checked, so your required checks stay a gate; a direct merge does not exist at any level. Two regressions in a row, or one change that shipped on its own and could not be measured, hand both gates back to a person, and only a person re-arms them. There is no timer. accept and merge set separately, per entity, over a brain-wide defaultthe arm bound to the checked commit — a moved head disarms itauto gates can stay closed until the judge agrees with peoplean admin-issued standing grant to auto-accept, bounded in calls and timea person switching auto-merge off on the PR is heard, not assumedthe implementer can never grant itself autonomy — the block is walled off docs/brain-dev/self-evolving.md
• Self-Improving Chat Agents i A person’s chat with a role is cut into episodes, first message to the end of that dialog, and each episode is graded whole: every message, reply and tool call, with earlier talks with the same person as context if you want it. A chat role that declares a loop enters it the way a scenario does. A change is never replayed against real people — it is judged on the role’s next episodes under one role version. an episode closes when the chat goes idle, or when the agent ends it itselfevery turn records the role version, so an episode spanning a change counts for neither sidea rubric or budget edit is not a new version — only what the role doesone privacy rule governs how the judge and the proposer write about peoplea rating card for you, if you want your own score in the mixcompaction moves an episode’s turns aside, never deletes what the judge reads docs/brain-dev/self-evolving.md
• Automation Tiers i The same scenario escalates without being rewritten. Tier 1 is one markdown file and the planner works out the steps. Tier 2 locks the plan it produced into a blueprint you can edit. Tier 3 replaces the plan with typed TypeScript that still inherits the whole engine — agents, tools, human approval, memory, monitoring — as callable infrastructure. Which tier runs is decided by which files exist, not by a setting. Tier 1 — one scenario file, planned fresh each runTier 2 — a frozen blueprint you edit by hand or in the wizardTier 3 — a pipeline in code, all three durable primitivesthe engine picked by file presence, overridable in frontmatterone scenario can own a primary pipeline plus auxiliariespipeline code hot-reloads in production, not just in dev docs/automation-tiers.md
• Eval System i A run is graded against the definition of done it was given, requirement by requirement — not a generic rubric — with a grounding check that catches a confident report of work that never happened, per-tool metrics and a typed failure category. Anything the engine runs unattended owes a daily grading ceiling, enforced where the money is spent rather than at parse time, so no config path can route around it. two levels: per-task definition of done plus run-level criteriathe deliverable verified from disk, not from the database copysampling by hashed rate plus a rolling per-day capgrading methods are brain files you can replacea failure taxonomy that groups entities failing the same waybooked before queued, so the reservation the cap counts is real docs/brain-dev/evaluation-and-improvement.md
• Self-Healing Workflows i When a run fails the engine spawns a recovery agent that diagnoses it, patches the plan blueprint itself and re-drives the run — the failure becomes an edit rather than a post-mortem. Categorised errors retry on their own, stuck tasks reset, and a process killed mid-run is swept back to a consistent state by a reconciler. a diagnosis tool, a blueprint patch and a retry, in one dialoguea patch that would orphan an existing task is rejected outrightbounded attempts, enforced inside the same compare-and-setduplicate triggers collapse onto one recovery per runa lost-run sweep for rows nothing is driving any more docs/workflow-fsm.md
• Git-Backed Hybrid Memory i Hybrid search by meaning and by word — the word leg matched by stem in the languages you list — deduplicated at write time, decayed exponentially, re-ranked for diversity — and searched automatically before every turn, so the agent never has to remember to remember. Every write lands in your git, committed by the sync daemon within minutes: diff what it learned last week, find the commit a bad fact arrived in, revert it. 0.85 meaning / 0.15 keyword, calibrated on real embeddings; age orders, never filterstwo zones: the engine-managed log and your own authored vaulta post-turn curator that saves corrections, gotchas and decisions onlya multi-process index that rebuilds and swaps itself atomicallydegrades to keyword-only rather than dying without an embedding keythe sync daemon commits every write to your own branch within minutes docs/memory.md
• Agent-Modeled SQL State i An agent that has to remember structured things — paused until 14:00, a streak, today’s challenge and its status — designs its own Postgres tables and evolves them with plain DDL mid-turn: no deploy, no migration, no PR. Every view named for its namespace is rendered into its context on every turn, and only a view that changed is sent again. Postgres computes the summary; no model summarizes it. one line in a role file turns it ontables are facts, views are what it sees, a query reaches the restscoped by role, so the next heartbeat sees the pause set from chata view, row and character budget per role, with an honest “more exist” markertwo roles may share a namespace — a writer and its reviewerdeterministic views, so an unchanged state costs nothing to resend docs/brain-dev/state.md
• Feature Contexts i A feature’s rules and data used to live in the role, so every turn paid for every feature the role served. Now the feature keeps them in a file of its own, and the engine attaches it only to a turn linked to it — a run that reaches it, a reply to a message such a run sent, a chat bound to it, a role that always carries it, or the agent opening it from its catalog. A turn with no link pays nothing. an entity key — one ticket, one client — filters its views to that entity’s rowsa role lists the contexts it may open or infer; none listed, none — a run’s own context and a chat’s binding still arrivethe catalog sits byte-stable in the system prompt; what attaches rides the turn’s taila CLI session is sent a view again only when its rows changea budget per context and per turn — what does not fit arrives as a stub saying how to open itwhat each turn carried, and through which link, recorded on the spend ledger docs/brain-dev/contexts.md
• Unified Agent Runtime i CLI agents and API models sit behind one interface — the caller picks with a string and never calls a different API. And an agent is not a request: it has a durable inbox, so a message you send mid-turn is picked up at the next stopping point instead of being dropped or starting a second run. CLI mode: child process, resumable session, tools over MCPAPI mode: in-process stream, history rebuilt each turn, tools injected directlysend / enqueue / call — one verb per intent, all durably queuedinterrupt preempts without eating the message it preemptedan agent puts a prompt on its own calendar — remind, snooze, nag until answereda stream-idle watchdog kills a silent harness instead of parking it forever docs/agent-flow.md
• Cascade / HTN Planner i Two ways to turn a goal into a plan. Cascade runs up to twelve focused stages — clarify, research, decompose, map capabilities, define done, group context, plan artifacts, review — each of which is a brain file you can rewrite. HTN does genuine recursive decomposition into a task network, bounded by construction and journaled step by step, so a crash resumes mid-tree. every stage prompt is a file in your repoeach stage validates itself and gets exactly one correction re-runclarification asks you real questions before it plansHTN linearizes its tree onto phases deterministicallya one-shot path for scenarios that do not need twelve stagesa live planning card, and cancellation that actually stops the model docs/workflow-planner.md · docs/htn-planner.md
• Phase-Based Workflow Engine i Tasks carry a phase number: phases run in order, everything inside a phase runs at once. A named context group runs its tasks one after another on a single shared agent that keeps its session across phases, while ungrouped tasks race in parallel — so "these three must build on each other, those five are independent" is a property of the plan rather than orchestration code you write. parallel within a phase, sequential between — read off the blueprint alonea context group keeps one agent session, across phasesa task can ask for its agent to be compacted before the next one runsoptional tasks can fail without failing the phase or the runrun status derived from the task rows, never stored and never disagreeinga resume skips finished phases and rebuilds the agent map from what completed docs/workflow-engine.md
• Human-Calibrated Judge i The judge earns trust instead of assuming it. A run can end with one rating card for a person — buttons for a single metric, a number per metric otherwise — and the answers are paired with the judge’s own grades. Until calibrated, cards keep coming; once judge and people agree they stop, a spot check carries on, and the loop’s automatic gates can be held closed until that agreement exists. never, always or until calibrated — per entityagreement measured per metric, over the newest pairs under the current judgetoo few pairs reads unknown, not finea tenth of runs keep their card after calibrationa new judge starts calibration over docs/brain-dev/self-evolving.md
• Ideas → Measured Experiments i Anyone with a hunch — you, a teammate, an agent — posts it for one entity: “try a shorter opener”. That entity’s next cycle works the oldest idea before anything the loop would propose itself, and every stage after the analysis is unchanged, so the idea comes back as a measured experiment with a verdict instead of an opinion. /idea in chat, a tool for agents, a panel on the dashboard — one entry point behind all threefirst in, first out, one idea per cycle, no priority knobevery surface refuses the same things in the same wordswithdraw an idea while it is still queuedthe idea stays linked to the cycle that took itposting one asks a person first, unless your brain says otherwise docs/brain-dev/self-evolving.md
• Skills System i A skill is a folder with a SKILL.md and optional scripts — the same open format Claude Code, Codex, Cursor and Copilot already read. The catalogue is three levels deep: names and descriptions in every system prompt, the body loaded when it triggers, reference files fetched on demand, so a hundred skills cost about ten thousand tokens instead of the whole window. the standard format, portable across every harnessprogressive disclosure with a graded budget, not a hard cutdeclared requirements — env, binaries, OS — checked before it is offeredinstall specs baked into the image and verified at buildper-skill enable and disable from the dashboardrecommendation without restriction: focus, never a lockout docs/skills.md
• Brain-Owned Tool Policy i One JSON file decides which engine and integration tools exist for your brain — by tool or by whole category, as an allowlist or a denylist out of the same mechanism. A disabled tool is rejected by name everywhere: the gateway, MCP, the webhook door. There is no "hidden but still callable" state. layered document, resolved most-specific-firstone gate covers both listing and resolutionyour own tools are exempt — the policy cannot lock you out of themhot reload, with unknown keys warned rather than swalloweda broken file keeps the last good policy instead of stripping every tool docs/tool-registry.md
• Progressive Task Enrichment i A task is not written once and executed. It starts as a title and a description, then accumulates its capabilities, its definition of done, its context group and its output artifacts across separate stages — each guarded by a coverage assert, so a task can never quietly lose a field between stages. id-keyed enrichment with a coverage assert at every stagecapabilities mapped before anything is authorizedthe definition of done written before the run, graded against after itcontext groups decide what shares one agent and what runs in parallelartifacts declared, then probed on disk when the task claims them
• ModelRef Grammar i One closed-format string names a model everywhere — the create wizard, the chat command, role frontmatter, your registry, the database column. claude · openai:gpt-4o · claude:openrouter:x-ai/grok-4.1 · smart@high · claude@high,codex@medium. Every name must be one the system knows: a typo fails at parse with a did-you-mean, never as a silent nonexistent role. a router segment points any CLI harness at OpenRouter’s four hundred modelsa per-step reasoning-effort suffix from minimal to xhighCLI harness and API provider are different fields, never one overloaded nameclosed-world parse: structure case-insensitive, the model tail verbatima single ref is a chain of length one, so nothing has a failover special casethe availability gate stays separate from the grammar gate docs/llm.md
• Robot OAuth i A provider marked auto-authorize hands its consent screen to a browser agent: it logs in, takes the one-time code out of the mailbox, clicks approve. Best-effort by construction — the human card is minted either way and simply stays put if the robot fails. And a token that later dies announces itself by name in chat and is re-authorized from that card, on a server with no inbound port open. an engine-shipped browser role with an anti-injection promptcredentials read inside the handler, never carried on the job payloadone-shot nonce, verifier and binding — a failure asks for a fresh cardthe human consent card is minted unconditionally, so nothing is lostthe blast radius is documented rather than hidden
• Role-Based Fallover Chains i A chain is one string: claude,codex. A role word resolves to an ordered list of concrete models out of your own registry, so "smart" means what you decided it means, per brain. What is worth failing over — a dead provider, an exhausted quota — is classified rather than guessed, so a genuine error still surfaces as an error instead of quietly burning the whole chain. a role word resolves to an ordered list of concrete modelsclassification decides what is worth failing over and what is a real errorrerouting is a first-class stream event, not a log linechains are same-mode and concrete — a CLI step never silently becomes an API callthe run-level retry sits above the chain, so a blip is not a failovera harness that dies mid-task hands its successor a transcript rebuilt from your Postgres docs/agent-flow.md
• Context Window Policy & Budget i Two halves of one question. The policy watches a live agent’s window and acts on the crossing — a nudge, then a compaction the agent queues on itself, journaled, so a restart cannot lose it and a second replica cannot repeat it, behind whatever you already sent instead of killing it. The budget answers what filled the window before the first message: tool definitions priced at their exact wire bytes, the prompt cascade attributed section by section, the context envelope part by part. per-role marks, edge-triggered, so a compaction re-arms them by data alonethe compaction never interrupts the turn you just senton-wire cost and deferred cost never conflated into one flattering numberanything known but unpriced counts as unmeasured, never as zerofindings that name the lever: no tool deferral, unused tools, memory-heavypercentages only where the runtime actually reported a window packages/context-budget/docs/context-budget.md
• Prompt Caching & Tool Deferral i What goes into a turn is placed by how often it changes, never by topic, because a provider’s cache breaks from the top down. The role’s system prompt stays byte-stable and is shared by every agent of the role; what moves rides the message stream, and only the sections that moved are re-sent. API models are cached per fallover step in that provider’s own dialect, and a role with a wide tool set pays for its few eager tools plus one search over the rest, not every definition on turn one. one cached prefix shared by a whole fleet of same-role agentsonly the sections that moved are re-sent, each as a self-describing updateAPI caching per chain step, in each provider’s own dialecta wide tool set deferred behind one provider-agnostic tool searcha tool the role always needs stays eager, by its own declaration docs/brain-dev/features.md § Context Placement
• System Prompt Cascade i One composer builds the system prompt for the CLI path, the API path and the budget report, so a report can never describe a prompt nobody sends. It assembles in fixed modules — identity, role, persona, environment, memory instructions, language, question policy, skills catalogue — each tagged, and each replaceable by putting a file at the same path in your own repo. engine defaults overridden file by file, not forked wholesaleevery section tagged, so the budget can attribute tokens to iteach harness takes it through its own instruction channel, with its own question rulesshort rules on every turn; the reference material fetched only when it is neededa role-prompt budget that names the sections that grewfourteen engine roles, your own personas over them, and a role gets only what it declares
• Per-Role Voice i A role speaks in a voice of its own and hears through a transcription chain of its own, both declared in its file — a warm Russian coach and a teacher reading drills in standard Dutch never share a timbre. Switch voice replies on in a chat and every answer arrives twice: the text first, as always, then the same answer as a voice note in the answering role’s voice. a role’s chain replaces the brain’s whole — no inherited fallback in the wrong languagea whisper step takes a prompt, so a speaker who mixes two languages is heard in bothhot: an agent changes a role’s voice with one write, and the next synthesis uses itthe voice reads the answer, not the markup — code and bare links stay in the textpipeline code speaks as a role by naming it, with no agent in between docs/brain-dev/voice.md
• Conversation Timeline i One append-only table is an agent’s history, and everything reads it: the chat card, the dashboard, and the API agent rebuilding its whole context every turn. Rows are ordered by a monotonic id rather than a timestamp, and compaction deletes a prefix without renumbering, so every cursor and checkpoint stays valid across it. one write path — stream write, then persistence, then derived notificationswhat persists is a closed list; deltas collapse into their terminal rowthe system half of the prompt stored content-addressed, rejoined byte-identicallytwo turns with different prompt hashes make a cache break diffablea paused turn writes its own ledger row, so pre-pause spend is never lost
• File-First Blueprints i The plan is a YAML file next to the scenario — no blueprint table, no server-side drafts. A run freezes a snapshot at creation and never re-reads it, so editing the plan mid-flight cannot change what is already executing, and the run’s slug is minted from its own id rather than a count, which keeps the artifact directory and the git branch valid forever. the file is the source of truth; git is the only historya frozen snapshot per run, task specs derived from it in memorythe run slug unique by construction — no count, no racecontent hashes decide when a plan has actually gone stalea readable title alongside the machine-readable slug
• Playwright Browser Agent i A headless browser as a sidecar service, reachable as ordinary tools — navigate, click, read, screenshot — from every CLI harness. It comes with an engine-shipped browser role that has the browser pre-attached and an anti-injection prompt, because a page you did not write is exactly where a prompt injection lives. a service you can turn off; nothing else changes when you dothe one role allowed to carry its own MCP serversany agent can spawn it as a sub-agent for a single jobthe same role the robot consent flow drives
• Entity Repair i A scenario whose frontmatter stopped parsing does not silently drop off the calendar. The repairer runs ahead of every reconcile, rewrites what it can atomically on disk — so the daemon commits a diff you can read and revert — and announces both outcomes to your status channel. What it cannot repair is reported once, not on every tick. runs at start, on a manual sync, and on every content changean atomic write, so a crash never leaves half a filerepairs arrive as a reviewable commit, not a hidden mutationunrepairable files deduped per path, so one bad file is not a siren
• Auto-Planning from Scenario Changes i Edit a scenario and the plan regenerates itself. Every reconcile tick hashes the manifest, the scenario files and the blueprints, skips what has not changed and what was just touched, and enqueues planning for the rest. Two layers of deduplication and a cross-process lock mean one change never plans twice, and a pass that failed halfway leaves the hash unset so the next tick retries. content hashes, not timestamps, decide what is stalea recently-modified guard, so saving mid-edit does not trigger a plana distributed lock across processes plus in-process coalescingthe hash advances only on a complete passskips and failures are events, not silence
• MCP Catalog & Store i A browsable catalogue of remote MCP servers with a two-click install: the official registry mirrored hourly, your own pasted entries, and whatever your config declares. Installing branches on the auth kind — an OAuth redirect, a pasted token, or nothing at all — and archival only happens after a successful non-empty sync, so a registry blip cannot wipe your catalogue. three sources: the official mirror, added by hand, and brain-declareda reverse-DNS allowlist when you want the official list curatedconnected entries pinned to the first page, computed in one batched joinarchival only after a good pass; a returning entry un-archives itselfsync results and entry counts as metrics rather than as a hope

control

who is allowed, who is watching, who owns the record

• HITL Gateway i A question, a permission request, an approval, a typed input form, a person intercepting an agent — one row in one table with one event pair, not six bespoke services with six ways to get stuck. Nine parallel requests hitting the same wall collapse into a single card, because the unit of decision is you, this scenario, these capabilities — not the request; one answer fans back out and wakes all nine, whether you give it in a minute or next week. six kinds × seven producers, each cell explicitly defined or refusedthe answer commits before its consequences, so a crash replays instead of re-askingresolve on any surface and the card closes on all of thema dedicated inbox chat, or your own DM if you never set oneevery interaction bound to a conversation, so timelines render without a joinanything left undispatched is swept by a reconciler, not lost packages/hitl-gateway/docs/hitl.md · HitlGateway.ts — one upsert; (xmax = 0) names the first writer
• Widgets i An agent, a pipeline or a hook opens a page for a person — in Telegram as a Mini App behind a button, on the dashboard, or in Claude, ChatGPT and VS Code as an MCP App. It runs both ways: what the person does there arrives as events your code reacts to or as turns of the agent, and the agent pushes state back while the page is open. A widget is one self-contained HTML file in your feature. every kind of Telegram chat the bot is in, plus its menu buttona sandboxed frame with no network by default; what it may reach is frozen when it opensevery tap, submit and tool call runs as the person at the page, checked against their tier therean approval can bring its own page — still one request, decided from any surfacethe agent previews the page as a person will see it, before anyone doesoutside Telegram, a plain browser signs the person in with Telegram docs/brain-dev/widgets.md
• Grant System i Every grant carries exactly one scope — scenario, agent, heartbeat or subject — with a TTL, a call ceiling and instant revocation. Approve a subset of what was asked, or answer in free text and let the model re-read what you actually meant, with the whole correction history kept for the audit. Nothing is ever decided by a timeout: there is no fast-approve, and no silent expiry into yes. four scope kinds; a grant attached to nothing is unrepresentablemint precedence heartbeat > scenario > agent — never principal-widedeclared grants pre-authorize an automation with no card at allan approved grant widens the agent everywhere it acts — its tools, its shell, its webatomic consume under the ceiling, plus scheduled and probabilistic cleanupnothing cascades: revoking is explicit, and the audit row survives docs/grants.md
• Hard-Stop Budgets i Dollar ceilings on metered spend — the brain by day and month, a scenario by run, day and month, a role by day and month — checked at the one point every agent turn passes, before any model is called. A spent budget refuses the turn and raises one card for that budget: +50%, ×2 or a figure you type, and the raise resumes the runs it parked. Agents may lower a limit on their own; raising one is always a person’s call. only metered spend counts — subscription usage never eats a budgetengine, brain and entity tiers, merged window by windowa workflow run parks and resumes, its finished tasks keptone card per budget and window, however many turns it refuseda pipeline reads the refusal as a typed category and decides what to dowith every budget spent, you still lift the stop from the chat you are in docs/brain-dev/budgets.md
• Emergency Stop i One command halts the whole operation: the scheduler braked, every queued, running or retrying workflow and pipeline run paused, every agent turn in flight cancelled — recorded as one action. Resume undoes exactly what that stop did and nothing more: a brake or a paused run that was there before stays. An agent may call either, and a person approves it. a capability of its own, granted to no role but a wildcard onewhat was in flight stops; a new chat message, hook or scheduled prompt still starts a turna run that will not resume keeps the stop standing for it alone“Stop everything…” on the dashboard; its notice offers only Resume while it standswhether a stop stands is one read any agent can make docs/brain-dev/features.md
• Every Page Is an Op i Over 260 reads and commands, each defined once in the engine’s op kernel and bound twice: the agent’s tool and the MCP tool. Every dashboard page reads and writes through them, so whatever a page shows, an agent can answer — with the same guards, the same refusals and the same words. Writes to brain files dry-run first and commit only against the bytes they read; anything that adds power goes through a widening op a person approves. grants, skills, memory files, models, providers, connections and repos — all opsrun traces and comparisons, the action log, your tables and key-value store — all readable by an agentdry run, diff, then compare-and-swap on the file’s hashrole files, chat access, model routing and budgets each split into narrow and widena refusal is a typed answer with a hint, never a crashevery committed command recorded as its caller docs/brain-dev/dashboard.md · docs/brain-dev/contract.md
• Live Brain Atlas i The whole operation as one live map: every role, scenario, heartbeat, skill, tool, integration and memory line, linked by what actually ran through them. Scrub back to any minute of the last week and watch it replay — each run drawn as a trace from its trigger through the role, the model and the tools to the memory it touched. Traffic your config never declared is drawn dashed, so drift between what you set up and what happens is something you see rather than grep for. clustered by engine layer or by business area, one per featurelive by default; replay at up to an hour a seconda red ring for failures, an amber one for work waiting on a persona failed data source reads unreadable, never zerorebuilt from the run ledger the engine already keeps — no extra event logsearch every entity, dormant ones included, with what is failing on it now docs/brain-dev/features.md § Brain Atlas
• Self-Evolving Console i Every self-evolving cycle on one page: each job in the loop as a card with its objective’s trend and whether it needs you, and one job opened on a single time axis — every merged change a step, every revert marked, the cycle in flight told in five phases from the grades that opened it to the lesson it filed. The policy each job runs under reads as sentences, with the tier that set every value. one list of everything the loop waits on you for, each with its one movethe pre-merge check drawn metric by metric, guards and objective apartthe proposal verbatim: current text, suggested text and whyaccept, skip or refine a proposal in your own words, from the pagegate and idea cards land in your chat — accept, refine or skip from the phonethe loop and grading kill switches on top, above every entity
• Control Plane Dashboard i Rebuilt phone-first: twelve places one level deep, one live stream per tab. The Inbox is a triage desk — every request owed to a person, two or more from one run folded into one stack, Boss mode on its tab row. Home reads in tiers, from “does anything need me?” down to the vitals; Runs reads what is going now, then the days before it; a session page is the whole conversation; the chat dock is the chief’s DM, one thread with Telegram. one Cmd+K across runs, agents, scenarios, skills, requests and people/go/ links that outlive a page move — the links agents write into chatthe features as a map of lego figures, each as big as what it is built ofa bottom bar on the phone, installable to the home screenyour own logo and favicon, served from the running braina browser shell into the brain root or any running service, replayed on reconnect docs/brain-dev/dashboard.md
• First-class Telegram surface i Not a notification sink — the primary interface. Commands, declared wizard flows, inline keyboards, live cards, file exchange, voice in and voice out. Nearly everything the dashboard does, you can do from a chat on your phone, including running a pipeline handler by name. per-chat active agent and model overridemulti-step wizard flows declared, not hand-rolled per commandany pipeline handler runnable straight from a chat commandsend resilience: format degradation, group migration self-heal, rate-limit retrydeep links straight into a run or a pipeline handlerin-chat introspection — ask it what it is doing right now docs/channels.md
• Secretary Mode i A bot marked secretary answers your chosen private chats as you, with zero bot chrome visible to the other side — no cards, no keyboards, no typing indicator, no failure bubble. Your own manual replies are recorded and time-stamped, so your engagement policy can read "the owner just answered this one" and back off. the connection owner is the auth principal; counterparts are never allowlistedidentity survives disconnect, reconnect and credential rotationapproval and question cards rerouted to your control DMa per-counterpart persona, so it speaks differently to different peoplehistory predating the connection readable under a blast-radius guard docs/secretary-mode.md
• Boss Agent i A coordinating agent watches the same queue you do and works it by policy — auto-approving what you delegated, routing questions to specialists, escalating only what genuinely needs a person. Start it from the Inbox, or ask an agent to: an agent’s start waits for a person’s yes, because it hands over a person’s authority. It acts through the same tools, the same compare-and-set and the same audit trail as a human would. a time-boxed run with every security knob fixed at startyou get first refusal on every card, by a configured head startit can never answer or cancel an interaction it produced itselfthe capabilities it may approve are an allowlist, not a prompt instructiona run summary: duration, turns, tools by count, decisions by kind and status docs/brain-dev/boss-mode.md
• Intercept an agent i Step into a live agent’s conversation while it works, steer it with ordinary messages, then hand control back — no cancel-and-restart, no losing what the run already knows. A plain message supersedes a pending question; a permission card is never dissolved by unrelated chatter, because permissions are decided explicitly. the pending row is the session marker, single-active enforced in the databaserelease re-dispatches a continuation turn and resumes the runevery other resume path is refused while you hold the wheelfrom the session page, or straight from the chat
• Runtime Escalation i An agent that hits a capability it does not hold neither fails silently nor needs everything pre-approved: the tool returns a structured missing-grant error naming a remediation path this particular caller can actually take, and the agent asks for exactly that capability, mid-run, naming what it was doing. The escalation tool is always in scope — even for an agent that declared no capabilities at all — so there is no bootstrap hole. a missing grant is a typed tool result, not a crash and not a liethe failure sentence names this caller’s own path, not a generic onethe escalation tool rides turn one, whatever the agent declareda burst of concurrent requests coalesces onto one card, one decisiona delegate is capped at its delegator, so nothing spawns its way around the carda sub-agent’s question goes to its parent first; you see it only if the parent escalates
• Cost & Spend Audit i Spend per model, split by billing type and by reasoning versus execution versus cache-hit tokens, attributed down to the scenario and the agent that spent it, with trends and a plain-language read of what moved. Subscription usage and metered usage are counted separately rather than blended into one flattering number. real metered spend and phantom subscription spend split everywhere it aggregatesten pivot dimensions, including who triggered itunit economics: cost per completed run, cost per passed evaluationmoney flow as a Sankey — context → provider → modela forecast gauge and a period-over-period overlay with spike markersthreshold-gated advice: cache leverage, retry overhead, evaluation blind spots
• Engagement Policy i One predicate decides what the bot reacts to and how — the single seam you customize per chat. It sees normalized signals only: scope, whether it was addressed, who forwarded what, media kinds, thread identity. No platform types ever reach your code. An ignore short-circuits before any cost: no typing indicator, no download, no agent run. the verdict can carry a steer instruction injected into that turnand an opaque context bag carried verbatim to every tool call, never through the modelengine defaults per scope: DM, group, thread, channel, businessnamed notify channels — an agent picks a name, never invents a chat idevery turn opens with where it came from — chat, thread, sender, your timezonea separate policy per persona on a multi-bot brain docs/brain-dev/engagement.md
• Agents Workspace & War Room i Several live agents pinned side by side in one grid, each streaming independently, each with its own conversation drawer — a war room rather than a tab per run. Sessions belonging to one lineage collapse into a single row with a status histogram, so a heartbeat that has ticked four hundred times is one line, not four hundred. list, live grid and cards, with the layout derived from the URLlineage rows carrying session counts and per-status histogramsrun-scoped matrices: every agent attached to one run, in one gridkeyset pagination a new session cannot restarttool calls, task lists and plans render as interactive blocks, not log lineseach lineage in one word — running, stuck, needs you, failed docs/agent-grouping.md
• Blueprint Editor i A full-page visual plan editor with a planner agent sitting inside it: phases and tasks you drag, execution config, the deliverable — and a chat pane editing the same draft you are looking at. It saves to your brain repo as YAML under a compare-and-set on the file’s hash, so git is the only history and there are no server-side drafts to reconcile. a rail of every blueprint, ad-hoc and repo-baseda planner-role chat pane working on the draft in front of youdrag-and-drop phases and tasks, with execution config and deliverableatomic YAML write guarded by the hash you loadedan unsaved-work guard on navigation and on unloada raw-YAML escape hatch with lock status
• Live Telegram Status Cards i A run, a plan, a pipeline, an agent turn — each gets one card that rewrites itself in place as it happens, debounced and back-pressured, instead of a stack of progress messages you scroll past. The answer streams into its own message alongside it, so the record of what was said stays separate from the record of what was happening. one message per turn, on a slot model, throttled and back-pressuredterminal stickiness — a finished card can never revert to a live keyboardanswer text streams into its own message, off the status carda reaction on your own message as a status channel: seen, working, donea plain outcome notice for a failure that had no agent to speak for itits control row: stop, run the queue now, cancel one queued message by its preview docs/channels.md
• Cross-Surface Mirroring i A conversation you continue on the dashboard shows up in the bound chat as the full conversation — delivered silently, so you are not re-pinged for something you just typed yourself. The surface that started the turn gets the notification; every other bound surface gets the quiet mirror. origin notified, everyone else served the silent copyfailed and cancelled turns advance the cursor without deliveringa card resolved on one surface loses its buttons on all of thema finished turn is guaranteed to deliver, reconciled from the rows
• Runs Timeline & Schedule i Every scheduled scenario and every heartbeat on one timeline — cron, next fire, last run, last result, and whether the grant it needs is still covered. Plus queue depth, reconciler status and a force-reconcile button, because "why did it not fire" should be one page, not three. a lane per job on one clock, its next fires up to a week aheadgrant coverage shown per scheduled entry, before it failslast result includes a tick whose delivery tool failed — not a false greenqueue stats and reconciler state beside itforce a reconcile from the page, live on scheduler eventsmissed fires counted per schedule: Late, then Down — a re-enable or an edit never trips it docs/heartbeats.md
• Provider & Tool Circuits i Is the circuit open right now — not how many rejections there were last hour. The page reads the shared breaker and the shared limiter straight out of Redis, so what you see is the state every process is actually routing on, with the cooldowns ticking down in front of you. Beside it every tool call is metered — volume, latency, failures by type and the agent that made it — so the tool quietly failing one call in ten is found before a run trips on it. live breaker state per provider, discovered rather than configuredthe current limiter counters beside itthe state the fleet routes on, not a derived metrica snapshot poll, plus a faster feed for the events themselvestool calls by risk, source and error type, denied apart from failed
• Daily Brief i Once a day the chief writes you a brief in your own direct message: what ran, what failed and why, what waits on you, what it cost. The facts come from the run ledger, not from memory, and the brief is an ordinary message of that chat — reply to it and the conversation simply continues. A quiet day sends nothing. your hour, in your timezone, or offthe chief’s voice, the engine’s factsone brief a day, even when a tick is delivered twicesend one now, from chat or from the dashboardthe doctor says why when there is no chief DM to write into docs/brain-dev/features.md § Daily brief
• Notice Gate i Everything the engine posts unasked — the card of a run nobody in that chat started, a failed hook, a model falling back, an alert — passes one gate that remembers what each chat was told. The same thing again edits the earlier message with a count instead of pinging you; a recovery marks it resolved; below your level, nothing is sent. The level governs the engine’s words, never an agent’s. routine, news or failure — your level brain-wide, or per scenario, heartbeat and hook“↻ ×N since 12:00” on one message instead of N notificationsa failure that persists is posted again after a window you seta message a person asked for is never gatedwhat stays quiet is still a row — the brief counts it, an agent lists it docs/brain-dev/notifications.md
• Decision Audit Trail i Who decided what, on every surface: each committed command — from the dashboard, an agent’s tool or MCP — each card answered in Telegram, each run cancelled from its card, each sub-agent question a parent answered, each change the loop accepted or reverted is one row with the actor, the person behind it, the op and the object. Agents read it through a tool, and a year of it is kept by default. a dry run, a refusal or a no-op writes nothingfilter by actor, person, object, feature or opa loop entity’s history includes the answers to its gate cardsa failed record never fails the decision it recordsretention is one manifest line, forever included docs/brain-dev/features.md § Action Log
• Capability Model i One vocabulary for “what may this agent do”: a domain:capability string with a risk level and an approval flag. Least privilege is the default reading of it: a role holds what its own file says — silence grants nothing, and “everything” is always written out — and the tools offered and Claude’s own shell, file and web tools derive from that one list. Skills and memory have allowlists of their own, read the same way — silence is none. tools declare what they provide, plan tasks what they require, and the two meet in the middlerisk is informational; the approval flag is what actually gatesClaude’s built-ins follow the grant; a new one stays off until the engine names ita role’s skills list is an allowlist — no list, no catalogthe role file is read every turn: a narrowing reaches live agents at oncea brain flips any engine default without forking the list docs/brain-dev/contract.md
• Prompt-Injection Defense i Anything the engine did not write — an email body, a fetched page, a webhook payload, a tool result marked external — is fenced with cryptographic boundary markers before it reaches a model. Invisible characters are stripped and lookalike angle brackets folded, so a payload cannot forge the end of its own fence. one wrapper on every external-content path, not per-integration guessworkboundary markers a payload cannot reproducehomoglyph and fullwidth bracket foldingsuspicious patterns logged, content preserved — no silent deletion
• Chat Access i The role belongs to the chat: everyone in it talks to the same role, with that role’s tools and memory. Each person there is an owner, a member, a stranger or blocked, and only an owner approves — wherever the card lands, and no setting changes that. A chat rule caps what a member’s turn may reach, whatever the role holds. You set it by telling the agent, on the dashboard, or in one file. a member’s turn is the role’s grant cut to the rule’s ceiling — none by defaultthe ceiling covers what the turn spawns, schedules and recalls, not only its toolsa narrowing applies at once; a widening waits for a person’s yes“why didn’t it answer Alex?” traced step by step, through your own policy codeevery button owner-only, except an answer from the person a question askedrefusals are private — the bot never refuses in public in a group docs/brain-dev/chat-access.md
• Structured Input Collection i An entry point can declare an input schema, and then nothing runs until it is filled: the card opens, no run row is created, and the answer re-enters through the same submit path. You can fill the fields, or say them in free text — or by voice — and the translator parses them back into the schema. a form before the run, not a half-created row waiting to be fedfree text and voice parsed back into the declared fieldsthe same mechanism mid-run, resolved through a durable waitno expiry by design — one card lives until it is answered or cancelled
• Event Stream i One firehose across agents, runs, pipelines, human decisions, hooks, the scheduler and the queues — live, searchable and correlated. A collector subscribes once at boot and keeps a replay buffer mirrored into Redis, so a tab opened an hour later catches up instead of starting blank. one subscription at boot, twenty thousand entries of replay behind itthe system-versus-user split declared in the event schema, not hardcoded in the UIevery envelope keyed by the first correlation id present in the payloadvirtualized rendering, so a busy brain does not melt the tabone shared reader — feature panels filter it instead of keeping a second bufferthe log tail beside it, filtered by run, agent or pipeline id — no query language
• Session Page i One session’s whole thread, live: messages, reasoning, work groups, plans and per-message usage. It also answers the forensic question — copy the exact full prompt that was sent, and open a diff on the turns where the system prefix moved, which is usually why a cache stopped hitting or a behaviour quietly changed. copy the full prompt, rejoined byte-identically from both stored halvesa marker on turns where the system prompt changed, opening a diffpending human decisions answerable inline in the timelinecleared conversations still reachable by deep linkstop, compact, clear, retitle, re-model and flush the inbox from the same page
• Published Artifacts Management i Every public link the brain ever minted, on one page — live, expired and revoked alike. Filter by status, visibility or publisher, preview the content inline, edit the title or the expiry, flip public to private, or revoke it outright. The audit trail records who published, who replaced and who revoked. an expired link can be un-expired, because a mistake is not a one-way doorpublic takes a person’s approval; private needs the admin logininline preview, so revoking is never a guesspublished, replaced and revoked, each attributed docs/artifact-publishing.md
• Integrations & Connections i What is connected, and what could be: every provider with its status, its env keys and its configured models, alongside the live OAuth connections with reconnect, force-refresh and revoke. The server catalogue browses on the same page, one click to install. the provider inventory read from the running config, not a static listreconnect, force a token refresh, or revoke — per connectionconnection health visible before an agent discovers it the hard waythe catalogue and your own connections side by side
• Multi-Bot per Brain i One brain, several bot personalities — each with its own token, persona and engagement policy, all sharing memory, skills, grants and database. Per-chat state is keyed by chat and bot together, because in a direct message the chat id is identical across every bot you run. the persona declares the name of an env var, never a tokenthe bot id derives from the token prefix, computable in any process with no API callone live turn per personality per chat, by constructionambient response elected deterministically — nobody, or exactly oneomit the list and you have exactly today’s single-bot behaviour docs/multi-bot.md
• Topic-per-Agent i A forum topic binds to an agent, so inside that topic the thread is the agent selection — no command, no prefix. Each lane has its own live turn, status card, queue and delivery cursor, which means two agents stream side by side in one chat. One coordinate carries it, so every surface-keyed mechanism keeps working unchanged. the thread is the selection; commands become thread-scopedparallel lanes, each with its own card, queue and cursorone coordinate makes routing, gating and stream rebinding work unchangeda deleted topic degrades to the main stream instead of losing messagesa card tap inside a thread operates that thread’s agent, not the chat’s