Bundles, triggers and budgets¶
What a profile carries beyond a model (bundles), what starts work without a person (triggers, run as service principals), the terms an unattended session runs under, and how money is counted. The A2A facade is in ../a2a.md.
1. Config bundles¶
A bundle is one versioned, hashed, immutable JSON document, assigned to profiles by
channel. Troupe.Protocol.Bundle owns its shape, so the plane, the worker and the
console check the same thing.
{"schema": 1,
"about": {"summary": "Reviews pull requests against the house checklist."},
"agents": [{"name": "pr-reviewer", "definition": "---\nmode: primary\n---\nYou review…"}],
"skills": [{"name": "review-checklist", "description": "How we review…",
"agents": ["build", "pr-reviewer"], "files": {"SKILL.md": "…"}}],
"mcp_servers": [{"name": "jira", "url": "https://mcp.jira.example/mcp",
"credential_ref": "JIRA_MCP_TOKEN", "header": "authorization",
"timeout_ms": 30000, "permission": "ask",
"tools": ["search_issues", "get_issue"]}],
"acp_agents": [{"name": "gemini", "command": "gemini-cli",
"args": ["--acp"], "hash": "sha256:…"}]}
An acp_agents entry is another vendor's coding agent the worker runs as a subprocess and
speaks ACP to, through the session's mounts; a team's grant narrows it as it does an agent.
A document with no schema key is schema 0, of which only mcp_servers is read; it is
accepted for planes upgraded under one and never written again.
about is what the apps' page on the profile says, never a session: at the top {summary},
the sentence under its name (≤ 200 characters, else the primary agent's description); on a
server {summary, tools}, a subtitle and a line per tool it carries, any where tools is
all (each ≤ 120). A worker from before about refuses a top-level one: upgrade it first.
On a pod the bundle's agents and skills, and Troupe's built-in agents, beat a working
copy's of the same name unless the profile says otherwise
(profile-options.md).
An agent loads the skills its own skills: opens (all or a list; none by default), and
a skill opens itself with agents: "all", or a list of names, Troupe's built-ins among
them, so build loads a bundle's skill without a copy of build in the bundle. A team's
grant narrows after both; admin.profile.agents says what each agent loads (Decision 980).
Validation. At most 4 MiB; only those six keys; names ^[a-z0-9][a-z0-9-]{0,63}$,
unique per kind. An agent's definition must parse as frontmatter plus prompt, may list only
skills the bundle has, and replaces an agent Troupe ships (build, plan, general,
explore, quick, answer, ask, reviewer, implementer, librarian,
orchestrate: every file in troupe_core's priv/agents/) only with override: true;
without it the bundle is refused, naming the agent. A draft's agent is also held to every
rule the daemon holds an agent file to (agents.validate: its keys, a mode, tools the
harness has, permissions that can apply, and the rest), refused in the same words,
agent <name>: <what is wrong>; what only a session can know, a model's provider or an MCP
server's tool, is not checked. A version already published is not checked again, so one an
older plane published still runs. The console's agent builder edits a bundle's agents as
fields and asks admin.agent.check for one at a time (#594). It starts from the profile:
a profile's page lists its agents as its bundle in effect has them (admin.profile.agents),
each with its mode, model, who it hands work to, its cap on turns, what it runs without
asking and which of the profile's teams may run it (a grant that allows other agents, or
denies this one, says no), and opens the builder on the channel the agent came from. The
builder edits the subagents beneath their primary and its delegations, per-tool
permissions, max_turns, skills and a model picked from the ones the plane knows the
provider serves (admin.profile.choices with the profile: its own model, the
organisation's models for people's machines, the models its sessions have run on, and the
ones its bundle names; the plane never asks a provider for its list). Copy starts a new
agent from one Troupe ships or one already published. A skill needs SKILL.md
(whose name, if present, must be its own), relative text files with no .., at most
512 KiB; its agents may name only the bundle's agents and Troupe's. An MCP url is https://, or http:// to a .svc host, and its host must pass
the policy's egress check. Publishing to a channel a pod profile follows also refuses a
url at a loopback, link-local, unspecified or cloud metadata address, in any spelling
(profiles-and-policy.md §4);
admin.bundle.validate is given no channel and does not make this check.
A profile that extends another. Any entry, of any kind, may say "override": true
(true or false, nothing else). It matters where a profile on this channel extends one on
another and the plane composes the two channels' bundles: an entry named like one in the
parent's bundle replaces it only with the flag
(profile-options.md, Decision 910).
MCP entries.
| Field | Meaning | Default |
|---|---|---|
name |
server name; tools appear as mcp.<server>.<tool> |
required |
url |
streamable-HTTP endpoint | required |
credential_ref |
the environment variable holding the token, ^[A-Z][A-Z0-9_]{1,63}$ — never a value |
none |
credential_mode |
whose credential goes out: profile (the token in credential_ref), person (the session owner's, credential_ref naming the slot), or client_credentials (the profile's own identity, below; no credential_ref) |
profile |
header |
where the token goes; authorization gets a Bearer prefix |
authorization |
timeout_ms |
per call | 30000 |
permission |
ask or auto; an agent definition may tighten it |
ask |
tools |
allowlist applied at discovery: an unlisted tool is absent, not denied | all |
stores |
files: where the organisation keeps files, which an agent asked for a file uses first (profile options) |
unset |
files |
with stores: files, the tools that save a file |
all of them |
about |
{summary, tools}: a subtitle and a line per tool for the profile's page (above) |
unset |
On publish the plane projects each server onto the profile's resource. A profile-mode
server with a credential_ref gets secretRef: {name: "troupe-mcp-<server>", key: "token"},
and the operator injects it as the credential_ref variable from an optional
secretKeyRef. So for every such server, create troupe-mcp-<server> with key token
in troupe-system, labelled troupe.dev/worker-secret=true: the operator copies it into
every troupe-w-<profile> whose profile follows the channel. Put its host in
allowedEgress. A person server is projected with its slot and a client_credentials
one with its mode alone; neither needs a Secret.
A server that takes machine callers by client credentials — a token that lasts an
hour, got with a signed assertion rather than a shared secret, with tools granted per
client — is marked "credential_mode": "client_credentials" and given no credential_ref
(a server with one beside it is refused). The bundle says only that: a channel serves
several profiles, and each profile is its own client there, with its own certificate and
granted tools, so who it is goes on the profile, in spec.mcpIdentities. Its key is kept in
OpenBao transit and signs without leaving it; there is no Secret to create. Setting up the
client, the certificate and the key, and rotating them, is in
profiles and policy (Decision 747).
Publish, adopt, retire. admin.bundle.publish {channel, content} validates, assigns the
channel's next version, stores the document under sha256:<canonical JSON>, pushes
config.updated to every pod on the channel and rewrites mcpServers on those profiles:
the channel's servers composed again with the ones each profile wrote itself, which a
publish keeps (Decision 910). A profile created on a channel, or moved onto one, gets the
channel's current servers with that write, not at its next publish. History is append-only;
a rollback is a new version with the old content. Pods fetch the version over the control
channel, verify the hash and materialise bundles/<hash>/{agents, skills, bundle.json}; one
that missed the push catches up at its next heartbeat. admin.bundle.get shows per profile
which pods are current, ahead or stale. admin.bundle.validate,
admin.bundle.preview and admin.mcp.check run the checks without publishing.
A new version applies to new sessions only; a running session keeps the version
recorded when it was created until admin.bundle.retire retires that version, after which
it moves to the channel's current version at its next activation, with a durable
config_upgraded event. A channel with nothing published offers the built-in agents, unless
the profile's spec.agents rule leaves some out (profile options).
A server that accepts only a signed-in person is not a bundle server. Some MCP servers
publish OAuth protected-resource metadata, answer a call without a token with 401, and
act as the person who signed in, refusing a service account's token: a bundle server's
shared token is what they refuse, and a person-mode credential_ref slot holds a pasted
value, not a sign-in refreshed every hour. Each person adds such a server to their own
mcp.json with an oauth.client_id and signs in from the TUI or the desktop app
(a server that wants you to sign in); the daemon
on their machine keeps and refreshes the tokens, and nothing of them reaches a pod or the
plane (Decision 741). What you provide is the client: register one public client (no
secret, PKCE, a loopback redirect such as http://localhost, any port where the provider
allows it) with the server's authorization server, grant it the server's scope, and give
people its id. Those tools serve their local sessions, and with their consent a session on
a pod through tools.register (Decision 748), never configured into the pod
(profiles).
2. Triggers¶
A trigger is a row the plane stores and something fires; firing creates a session as
the trigger's principal through the same session.create a person uses, so grants,
budgets, agents and terms all apply. Triggers, principals and runs live only in PostgreSQL:
unlike the session index they cannot be rebuilt from object storage. In gitops mode a
repository holds the triggers' definitions as well (below).
| Field | Meaning | Default |
|---|---|---|
team, name |
owner, and ^[a-z0-9][a-z0-9-]{0,62}$ unique per team |
required |
principal |
a principal of the same team, which the session runs as | required |
profile, agent |
where it starts and which primary agent; one the plane does not have is saved, and fails at each firing (the gitops reader refuses it up front) | profile required |
enabled |
a disabled trigger refuses to fire | true |
source |
{"kind": "schedule", "cron": "…", "tz": "UTC"}, {"kind": "webhook", "provider": "…"}, {"kind": "webhook", "provider": "github", "repository": "owner/name", "label": "…", "command": "…"} (Runs on GitHub) or {"kind": "manual"}; a tz other than UTC is refused |
required |
prompt_template |
≤ 64 KiB, with {{event.issue.key}}, {{trigger.name}}, {{run.fired_at}} placeholders; a missing path renders empty, nothing is escaped |
"" |
terms |
§3 | {} |
visibility |
private or team |
team |
review |
required or none |
required |
notify |
subjects granted collaborator on every run's session |
[] |
notify_url |
an absolute http or https URL posted the run's outcome when it ends, never its content; not loopback (localhost included), unspecified, link-local, multicast, a cloud metadata address (fd00:ec2::254, 100.100.100.200) or in 100.64.0.0/10, by address, in any IPv6 spelling of one, or by a name that resolves there (Decision 866), and a host the policy's egress allows, checked when saved and again at send, and posted to the address the second check passed, following no redirect |
none |
concurrency |
cap on live runs, 1–100; a firing over it records a skipped run |
1 |
Cron is five fields (*, */n, n, a,b, a-b, a-b/n; day-of-week 0–7), UTC
only, no names or @daily. The in-plane scheduler is one cluster-wide singleton
ticking every 30 s. Each tick fires every enabled schedule once for the latest due minute
after its last firing, with idempotency key cron:<id>:<minute>, so a plane that was down
fires once, not once per missed minute; a trigger that has never fired fires only if its
minute is within the last 120 s.
Firing by hand or from outside. trigger.fire {trigger, idempotency_key, event} on
/rpc, by the trigger's principal or an admin of its team, writes the run row first, so two
callers racing on one key get the same run: skipped stays skipped, failed is retried under
the caps as a new firing is, a run with a session is handed it and a fresh token, and one
still making its session is waited for, up to five seconds, after which the answer is 409
naming the run. event is capped at 16 KiB. admin.trigger.run fires one by hand, as the
console's Run on a trigger's page does (its confirmation, Run the trigger's name
now); a second click or a retry by the same person less than a minute after the first is
the run the first one made, whatever minute the clock has turned to between them.
A trigger's own URL. A trigger with a key is fired by POST /trigger/<id> with
Authorization: Bearer <key> and a JSON object as the body, which becomes the run's
event. The key fires that one trigger and nothing else, which makes it the credential to
give a CI job or a provider's webhook; a wrong key and an unknown id get the same 401. An
Idempotency-Key header names the run; without one, a retry within a minute of the firing it
repeats, against the same revision, gets the run that firing made, whatever minute the clock
has turned to between them. The answer is 202 with the run and where its
session is, as from trigger.fire; a disabled trigger is 403, an event over 16 KiB 413
and a team with no budget left 402. source.kind: webhook says a trigger is meant to be
fired from outside, this way or by an executor that calls trigger.fire.
A webhook trigger is made with its key: the admin.trigger.put that creates it answers
key and url once, and the console shows them once with a button that copies the key.
admin.trigger.key.rotate (the console's Rotate, typed by the trigger's name) mints a
new one at once, shown once with the URL and kept as a salted hash; it is how a webhook made
another way (a resource in gitops mode, or a trigger changed to a webhook) gets one. Only
a webhook that names no repository has a key: a schedule is fired by the plane, a manual
trigger by a person or a principal, and a trigger on a GitHub repository by the App's
signed deliveries, so rotating one of those is refused, and a trigger whose source changes
to one of those loses its key (changed back, it has none until a rotation; a listing's
has_key says which have one).
Runs store only what the plane decided — created, skipped, failed — and read the
rest from the session: running, waiting (on an approval), done, failed. A turn the
harness stopped is failed with its failed_reason: tool_failures, a tool that kept
failing, or agent_failed, an agent that kept crashing. A run that has had no session for
ten minutes, because the request that fired it ended before it made one, is ended failed
by the scheduler with the reason on the run and a trigger.run.end audit entry, so it no
longer holds a place against the caps. Firings that race are counted one after another,
under the trigger's row and, for a trigger on a repository, under one lock for every
repository cap, so a concurrency of 1 starts one of them. admin.runs.list and
admin.run.review are the inbox, which the console's Runs and review screen draws for
a platform admin and a team admin alike (console.md). A
notify_url is posted {trigger, run, source, session_id, fired_at, state,
done_reason, failed_reason, pull_request} when the run is done or failed, with
state as the run listing gives it and pull_request the link to the draft pull request
the run opened, or null.
Triggers from a repository¶
In gitops mode (gitops.md) a repository holds the triggers as well as the
profiles (Decision 737): Trigger resources in the plane's namespace, applied by Flux or
anything like it. Every fifteen seconds, after the profiles, the plane lists them and makes
its triggers follow. A new resource becomes a trigger, a change changes it and makes a
revision as an edit does, and a resource that goes takes its trigger with it, runs and key
included. Each is audited as trigger.put or trigger.delete by system:gitops, with the
revision it made.
One resource per trigger, named <team>.<trigger>: a trigger's name is unique within
its team and a resource's within its namespace, a dot is in neither, and a team said once
has no second field to disagree with. The principal is named by subject.
# triggers/platform/nightly-digest.yaml
apiVersion: troupe.dev/v1alpha1
kind: Trigger
metadata:
name: platform.nightly-digest
namespace: troupe-system
spec:
principal: svc:platform/nightly
profile: standard
agent: reviewer
enabled: true
source:
kind: schedule
cron: "0 3 * * 1-5"
tz: UTC
promptTemplate: |
Summarise yesterday's merged pull requests for the platform team.
terms:
budgetMicros: 2000000
maxTurns: 30
approvals: deny
visibility: team
review: required
notify: [lead@example.com]
notifyUrl: https://hooks.example.com/troupe
concurrency: 1
| Trigger | Resource |
|---|---|
team, name |
metadata.name, split at its dot |
principal |
spec.principal: svc:<team>/<name>, a service principal of that team |
profile, agent, enabled, source, visibility, review, notify, concurrency |
the same names, with the defaults in the table above |
prompt_template |
spec.promptTemplate |
notify_url |
spec.notifyUrl |
terms (§3) |
spec.terms, spelt budgetMicros, maxTurns, wallClockSeconds, approvals |
A field the manifest leaves out is its default, not what the trigger said before.
What is used. A resource is used only if admin.trigger.put would have saved it (its
name, source and cron, the keys of its terms, its visibility, review, cap and notification
target) and what it names is here: a team the plane has, a service principal of that team,
and a profile the plane has. Profiles are read first in the same pass, so a trigger and its
profile can arrive in one commit. A spec field a Trigger has not got is refused too: the
CRD keeps unknown fields so that a misspelt promptTemplate reaches the plane rather than
making a trigger that asks for nothing. One that fails is refused: a new one gets no
trigger, and a changed one leaves the trigger as the last version that passed, still firing.
The reasons are in the log once, in admin.triggers.list (each trigger carries gitops:
the resource, the generation it was read at, and a problem of refused or missing with
reasons; a refused resource with no trigger is listed by name, to a platform admin with
team null where it names no team the plane has), and on the console's Triggers page.
Locked. The Triggers page is marked Held in a repository, with no form, no switch and
no delete, and admin.trigger.put (switching one on or off included) and
admin.trigger.delete are refused as managed_by_gitops and audited with
outcome: refused. Switching a trigger off is a commit that sets enabled: false. In a
hurry, suspend the applier and patch the resource, which the plane follows within fifteen
seconds, or disable the trigger's principal, which stays the console's. A trigger the
cluster has no resource for (missing, below) may still be deleted.
What stays the plane's. Running one now (admin.trigger.run), its revisions and runs,
and its key, which is never in a resource: a key in a manifest would be a credential in
a repository, and a reference to a Kubernetes Secret would give the internet-facing plane a
grant on Secrets its Role deliberately lacks, only to hash a value it can mint itself. A
rotation also answers a leak, which cannot wait for a review and an applier's interval, so
admin.trigger.key.rotate works in gitops mode as in direct. A trigger's row is changed
in place when its resource changes, so its URL (/trigger/<id>) and its key survive every
commit; a trigger removed from the repository and added again is a new trigger, with a new
URL and no key.
Teams, principals and grants stay in the plane's database, and a trigger names them. Enable the team and make the principal before the manifest merges, or the resource is reported until they exist. Disabling a team deletes its triggers; their resources are then reported as naming a team the plane does not have, until they leave the repository.
On a direct plane the same resources are listed and never followed: an administrator
copies one into a row (admin.trigger.copy) and copies it again when it changes, and the
console says which rows have drifted (gitops.md).
From a running plane. admin.profiles.export gives every trigger as
triggers/<team>/<trigger>.yaml, beside the profiles and the policy, with its document and
nothing the plane keeps; a trigger with a key says so in a note, and the key keeps working
after the switch (gitops.md).
Applied by Flux in a Kustomization of its own, after the profiles':
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: troupe-triggers
namespace: flux-system
spec:
interval: 5m
sourceRef:
kind: GitRepository
name: fleet
path: ./triggers
prune: true
dependsOn:
- name: troupe-profiles
Of its own because Flux applies a Kustomization as a whole, and a trigger the API server
refuses should not hold back a profile. With prune: true, a manifest removed from the
repository deletes its resource and the plane then removes the trigger. A directory per
team is also what a CODEOWNERS file can give each team to review.
3. Unattended session terms¶
session.create, and so every trigger and A2A task, accepts terms, validated before the
session exists and re-sent on every activation:
| Term | Range | Default | Effect |
|---|---|---|---|
budget_micros |
≥ 1, capped to the least any ceiling above it has left (team, person or platform); none left refuses the session with budget_exhausted |
5 000 000 | reserved at each activation |
max_turns |
1–500 | the agent's own | ends the session done with budget_exhausted; with this or wall_clock_seconds set, every limit of the session stops it rather than asking |
wall_clock_seconds |
60–86 400 | the agent's own | same, counted in working time: a turn's time, not the time the session is awake |
approvals |
wait or deny — there is no auto |
wait |
wait leaves the approval for a person; deny answers no. A trigger that needs no approvals runs a profile whose bundle sets those tools to auto. With neither limit above set, a spent budget asks the person attached, as on a laptop, and deny answers that no too |
A session whose origin is a trigger or A2A and that nobody has marked reviewed is in the
review queue (needs_review on sessions.list and admin.sessions.list);
session.review clears it, audited. A person's own sessions are never in it.
4. Budgets¶
- A team's defaults come from the settings in force when it is enabled
(configuration.md Part C); after that,
admin.team.update. There is also a platform budget and a per-person budget;admin.budget.explainsays which ceiling binds and why,admin.person.budgetone person's. - A profile's budget (Decision 910). A worker profile may carry
budget_micros, a ceiling on what the sessions on it spend in a calendar month (UTC), whoever starts them and in whichever team. It is asked after the person's and before the team's, as their rung is, with the same reservations; a session it refuses isbudget_exhaustedwithscope: profile, the profile's name and a sentence saying it is that profile's. A profile that extends another has the lower of its own and its parent's, and one set higher than its parent's is refused; each profile's sessions count against its own ceiling, not its parent's.admin.budget.explainwithprofilelists it, withset_by, the profile whose budget is in effect;admin.profile.getanswersbudget, what is spent and held this month. The console sets it on the profile's editor, in dollars, through the usual preview and audit. - Reservation, then spend. A session reserves a slice at activation (
terms.budget_microsor the default); the ledger records what model calls actually cost, one row per gateway request id. A reservation is granted when spend plus reservations stays within the budget, written before it is granted, and released when the session goes dormant. Zero is unlimited. - The period. A
monthlyteam counts what it spent since midnight UTC on the 1st of the month, and a team refused at its ceiling can start sessions again from then;nevercounts everything. A person's cap and the platform's (and the deployment's) are always monthly in the same way, whatever their teams' periods: a person's counts what they spent this month in every team, the platform's what everybody did. - One budget actor per team, registered cluster-wide, which is why plane replicas must be clustered.
- A call's cost is the gateway's (LiteLLM's in a streamed call's usage, or its cost
header), else the catalog's price or
models.prices, on a pod the profile'sllm.prices; a model priced nowhere counts as free. A call with no gateway request id is recorded asseq:<session>:<n>, which the reconcile counts as unmetered (integrations.md §5).