How LLM agents work — and how trip2g runs them

Roles as notes

An agent in trip2g is called a role. A role is a note in your vault like any other, but read by the fleet daemon instead of a human:

• Frontmatter = configuration: which model to use, which paths the agent may read (read_patterns), which it may write (write_patterns), what triggers it (trigger_include, trigger_on), budget limits (max_tokens, max_steps), timeout (timeout_seconds), concurrency policy (concurrency), and fan-out mode (for_each).
• Body = the instruction, rendered as a Jet template against four variables: changed_files, change_file, attached_notes, depth.

A minimal role note:

---
model: gpt-4o-mini
tools: [read_note, write_note]
read_patterns: ["drafts/**"]
write_patterns: ["published/**"]
mode: change
trigger_on: [update]
trigger_include: ["drafts/**"]
max_tokens: 4000
max_steps: 6
concurrency: skip
---
You are an editor. Read the draft at {{ change_file.Path }}, rewrite it for clarity,
and write the result to published/{{ change_file.Title }}.md.

Triggered by note changes

When you save a note that matches a role's trigger_include patterns, trip2g fires a change-webhook delivery to the fleet. The fleet verifies the HMAC signature, renders the role body as a Jet template against the trigger context, and runs the agent loop.

The fleet registers and maintains these webhooks automatically through a reconcile loop — you do not set up webhooks by hand. Drop a role note into the agents folder and the fleet registers the corresponding webhook on the next poll. Remove the note and the webhook is deregistered.

The scoped tool loop

The agent has five tools:

Every read and write is checked against read_patterns and write_patterns using doublestar glob matching. An out-of-scope request is rejected and the error is fed back to the model so it can adjust — denials are never silently swallowed. The model is told in its system prompt which patterns apply, and any attempt to go outside them is surfaced explicitly.

A role can restrict which tools are available at all via the tools frontmatter field. finish is always available regardless.

Writes happen during the run, not after: each write_note or patch_note call issues an immediate note update through the per-delivery scoped token. The fleet reports changes: [] in the HTTP response because the writes are already applied by the time the response is sent.

Safety controls

Three hard limits enforce the runtime budget. The model cannot override any of them:

• Token cap (max_tokens): if cumulative token usage reaches the cap before finish is called, the run stops with status capped.
• Step cap (max_steps): if the tool loop reaches the step limit without finish, the run stops with status max_steps.
• Timeout (timeout_seconds): the run context is cancelled and the loop stops. Default is 300 seconds.

The fleet applies a ceiling on top of the role's own settings: effective = min(role.max_tokens, fleet.token_ceiling). A role author cannot request more than the fleet operator's configured maximum.

Loop prevention (max_depth): trip2g passes a depth counter with every delivery. When a role's write triggers a subsequent webhook delivery, the depth increments. If depth >= max_depth, trip2g drops the delivery without running it. Setting max_depth: 1 on a role that writes to its own trigger path is enough to prevent self-retriggering entirely.

Concurrency (concurrency: skip): if a delivery arrives while a previous run for the same role is still in flight, the new delivery is dropped rather than queued. This collapses rapid note-edit bursts into a single agent run per role.

Templating and fan-out

The role body is a Jet template. Four variables are available at render time:

for_each: changed_files runs the agent once per changed file in the delivery, with change_file set to that file. for_each: attached_notes runs once per attached note. Without for_each, the agent runs once with the full lists.

Secrets are never exposed to the template. Referencing an undefined variable in a Jet template is a render error that stops the delivery before any LLM call is made.

Worked example: the Krisp pipeline

The Krisp case shows how two chained roles turn raw call transcripts into a structured knowledge graph with wikilinks.

transcripts/<id>.md   raw transcript (written by ingest, never by the LLM)
   │  save fires change_webhook → transcript-segment role
   ▼
segments/<id>.md      topic map (Minto headlines + [MM:SS–MM:SS] time ranges)
   │  write fires change_webhook → transcript-wiki role
   ▼
wiki/<id>.md          knowledge note with [[WikiLinks]] into the vault graph

transcript-segment triggers on transcripts/**, reads the transcript from the delivery payload (change_file.Content), and writes a segmentation map to segments/ using only the write_note tool.

transcript-wiki triggers on segments/**, reads the segment map (delivery payload) and the original transcript via read_note (covered by read_patterns: ["segments/**", "transcripts/**"]), and writes a wiki note with [[WikiLinks]] to wiki/.

Both roles use for_each: changed_files and max_depth: 3. The chain terminates because nothing triggers on wiki/**. In a validated run using qwen/qwen3-14b via OpenRouter: step 1 completed in ~7.6K tokens (2 steps), step 2 in ~11.2K tokens (2 steps).

The raw transcript is written by a deterministic ingest step — not the LLM. This keeps the source auditable and re-processable: when the prompt or model improves, re-run the roles against the same raw note.

What's coming: the executor role kind

A second role kind (executor) will run Python or shell code for steps that do not need a language model — pagination, field mapping, format conversion. Same role-note format, same trigger mechanism, no LLM cost or latency.