trip2g Agent Runtime — Unified Design (Fleet-as-Executor)

model: gpt-4o-mini
tools: [search, read_note, patch_note]
read_patterns:  ["boards/**", "roles/**"]
write_patterns: ["boards/**"]
max_tokens: 4000
max_steps: 6
mode: change
trigger_include: ["boards/sprint.md"]
trigger_on: [update]
attach_notes: ["boards/**", "roles/**"]
max_depth: 1
concurrency: skip

url             = <CallbackURL>/deliver/<urlKey("roles/triage.md")>
include_patterns= ["boards/sprint.md"]
attach_notes    = ["boards/**", "roles/**"]
read_patterns   = ["boards/**", "roles/**"]
write_patterns  = ["boards/**"]
pass_api_key    = true
on_update       = true
max_depth       = 1
concurrency_mode= skip
transform_jsonnet = ""           # identity; fleet expects the native payload
description     = "fleet:<FleetID>:roles/triage.md#<ver>"   # reconcile marker, no managed_by column

2b. Second worked example — forms→inbox triage (cron lane)

Validates the cron path + the work-available/cursor patterns. A public form (existing internal/case/submitform) collects "request to be added to the knowledge index." Submissions land in form_submits + EAV — not notes — so this is a cron role, not a reactive one:

• roles/inbox-triage.md frontmatter: mode: cron, cron_schedule: "*/5 * * * *", read_patterns: ["index/**"], write_patterns: ["index/**"], tools: [search, read_note, patch_note], small budget. Body = the triage instruction (decide KB-inclusion).
• The fleet reconciles a cron_webhook (url=fleet callback, pass_api_key=true). On each tick trip2g POSTs; the fleet lists unprocessed submissions via the admin lane (admin.formSubmits), decides per item, writes accepted ones as index/<slug>.md (scoped token, updateNotes), and calls markFormSubmitProcessed — which is the cursor/high-watermark: advance only after a successful write = at-least-once + dedup by submit id = effectively once.
• Alternative (reactive): a tiny submit→note bridge writing inbox/<id>.md, then the attach_notes: ["inbox/*.md"] work-available gate + atomic-claim semaphore apply (same as the kanban lane). Prefer the cron lane first — zero new trip2g code.

---

Reused (lean on, do not rebuild)

Capability	File:line
Agent loop (token hard-cap, max-steps, Result.TokensUsed/Steps)	internal/agentruntime/runtime.go:79,111,113,53-54
KB interface + ScopedKB glob gating	agentruntime/kb.go:21, scope.go
OpenAI-compatible LLM (configurable BaseURL)	agentruntime/openai_llm.go:19
HMAC sign/verify, Deliver, retry/backoff	internal/webhookutil/hmac.go:18, httpclient.go:27, deliver*webhook handleDeliveryError
Glob matching + JSON array parse	internal/webhookutil/patterns.go:11,23
Admin webhook CRUD mutations	internal/case/admin/{create,update,delete}webhook + cron twins; schema.graphqls:3240-3251
Per-delivery token minting (Depth+1, Read/WritePatterns)	deliverchangewebhook/resolve.go:88-92
shortapitoken acceptance → appreq scope	internal/case/checkapikey/resolve.go:54-62,123-143
Note actor pipe (user/api_key/client attribution)	cmd/server/notes.go:116 → insertnote/resolve.go:91-100 → queries.write.sql:27
Jsonnet VM (MaxStack=500, ExtVar, EvaluateAnonymousSnippet)	internal/frontmatterpatch/evaluate.go:11,53-57
Single serialized write connection (makes conditional INSERT race-free)	cmd/server/main.go:153, graphql.go:47
Standalone-cmd-in-module pattern; ArrayFlags	cmd/agent, cmd/businessdemo, appconfig/config.go:36
Discovery surface: notePaths(like), note(path:), noteChanges SSE	schema.graphqls:1528,152,168,2048

Net-new

• cmd/fleet/main.go + internal/fleet/ (config, fleet, role, discovery, reconcile, client, remotekb, handler, secret).
• internal/jsonneteval/ (NewVM/EvalJSON/Validate) — extracted shared seam.
• patch_note tool + AgentChange.Find/Replace/Kind in agentruntime (coordinated runtime edit, then re-freeze).
• Server enforcement of WebhookWritePatterns/WebhookReadPatterns (the security fix).
• 4 additive trip2g columns sets across 2 migrations + CRUD plumbing.
• Stale-lock janitor cron.

DROPPED vs the prior doc (do not build)

Dropped	Why
executor_mode column	trip2g no longer chooses an executor; it always POSTs
In-process LLM executor in trip2g	executor lives in the fleet
instruction_llm mode	not a mode; the fleet runs the loop
internal/notekb in-process apply branch	no in-process apply; fleet writes via the API
In-process canonical-apply branch in deliverchangewebhook	webhookutil.Deliver only; applyAgentChanges no-ops on empty changes
model / max_tokens / max_steps / tools / read_patterns / write_patterns / agent_jsonnet / cursor_path columns	all live in frontmatter
managed_by column	reconcile dedups via the existing description field
secret_vars / header_groups / webhook_secret_vars tables	reuse secrets table + ChangeWebhookSecretPrefix convention
Prior-doc §6 migration timestamps' DDL	reassigned here; strike §6

---

5a. cmd/fleet daemon — discovery, frontmatter, reconcile, auth, delivery, budget

Responsibility: standalone trip2g-module binary that runs agentruntime.Run as a well-behaved external webhook target. Its own process → the "embed in app" Service-Package rule does not apply; it declares its own small types with injected deps (Env-style for testability).

Files: cmd/fleet/main.go, internal/fleet/{config,fleet,role,discovery,reconcile,client,remotekb,handler,secret}.go (+ *_test.go).

Config:

// internal/fleet/config.go
type Config struct {
    FleetID       string        // reconcile marker prefix "fleet:<FleetID>:"
    ListenAddr    string        // ":9090"
    CallbackURL   string        // trip2g-reachable base; webhook url = CallbackURL+"/deliver/"+urlKey(path)
    Trip2gBaseURL string
    AdminAPIKey   string        // X-API-Key, EnableMcpAdminTools=true — FULL ADMIN (see security)
    FleetSecret   string        // per-role secret = HMAC(FleetSecret, FleetID+":"+path+":"+ver)
    LLMBaseURL    string        // OpenAI-compatible; fleet-local, NOT a trip2g secret
    LLMAPIKey     string
    DefaultModel  string
    TokenCeiling  int           // non-overridable: effective = min(frontmatter, ceiling)
    StepCeiling   int
    AgentsFolder  string        // "agents/" -> notePaths like "agents/%"
    OfferedTools  []string      // role.Tools must be a subset (fail-fast)
    PollInterval  time.Duration // PRIMARY change-watch (SSE is an optimization, see open Qs)
}

Role (parsed note):

// internal/fleet/role.go — flat schema maps 1:1 onto NoteView.meta + webhook columns
type Role struct {
    NotePath      string   // identity / reconcile key
    Body          string   // the instruction
    Model         string
    Tools         []string
    ReadPatterns, WritePatterns []string
    MaxTokens, MaxSteps int   // pre-clamp
    Mode          string     // "change" | "cron" | "both"
    Change        *ChangeTrigger
    Cron          *CronTrigger
    TransformJsonnet string
}
func ParseRole(notePath, body string, meta map[string]string) (Role, error)
func (r Role) Validate(offered []string) error // tools ⊄ offered -> fail fast

Auth lanes + reconcile + correlation:

// internal/fleet/client.go
func (c *Client) AdminGraphQL(ctx, query string, vars map[string]any) (json.RawMessage, error) // POST /_system/mcp, X-API-Key
func (c *Client) UpdateNotesScoped(ctx, token string, changes []ScopedChange) error            // POST /_system/graphql, Bearer

• Discovery: notePaths(like:"<AgentsFolder>%") then note(path:) per hit, body via NoteView.content, frontmatter via NoteView.meta (flat key/raw). Admin lane.
• Reconcile (reconcile.go): desired set = one change/cron webhook per role; idempotent Create/Update(specHash changed)/Delete keyed by the description marker fleet:<FleetID>:<path>#<ver>. Secret is derived and passed as input.Secret on create (createwebhook/resolve.go:64); UpdateInput has no secret field, so rotation = bump <ver> → Deregister+recreate.
• Correlation: URL path /deliver/<urlKey(notePath)> — the delivery header X-Webhook-ID is the delivery id, not the webhook id, so the role key is encoded in the URL the fleet itself registered.

Delivery handler + budget clamp:

// internal/fleet/handler.go
func (f *Fleet) ServeDelivery(w http.ResponseWriter, r *http.Request) {
    role := f.registry[roleKey(r)]                 // 404 if unknown
    if !webhookutil.VerifyHMAC(body, f.secret(role), sig) { http.Error(w, "", 401); return }
    in := agentruntime.Input{
        Instruction:   role.Body,
        ReadPatterns:  role.ReadPatterns,
        WritePatterns: role.WritePatterns,
        Model:         orDefault(role.Model, f.cfg.DefaultModel),
        MaxTokens:     min(role.MaxTokens, f.cfg.TokenCeiling), // non-overridable cap
        MaxSteps:      min(role.MaxSteps,  f.cfg.StepCeiling),
        LLM:           f.llm,
        KB:            newRemoteKB(f.client, payload.APIToken, payload.AttachedNotes),
    }
    res, _ := agentruntime.Run(ctx, in)
    // changes:[] — writes ALREADY happened via remoteKB during the run (avoids server double-apply)
    writeJSON(w, 200, resp{Status: res.Status, Changes: nil, TokensUsed: res.TokensUsed, Steps: res.Steps})
}

Cooldown/skip path returns 202 Accepted, which the server explicitly excludes from change-parsing (deliverchangewebhook/resolve.go:152 != http.StatusAccepted).

Narrow validation tests: ParseRole/Validate (tools-subset fail-fast); budget clamp min(); Reconcile diff (create/update/delete idempotency, foreign webhooks untouched); handler HMAC 200/401/404; happy path asserts exactly one UpdateNotesScoped with the scoped token and changes:[], admin key never used for writes; RemoteKB overlay (attached read = no API call); cooldown → 202, no LLM run. All offline with moq Client + stub LLM.

---

5b. internal/fleet RemoteKB — attach_notes seeding, scoped token, spend reporting

// internal/fleet/remotekb.go
type remoteKB struct {
    client  *Client
    token   string            // per-delivery scoped token from payload.api_token
    overlay map[string]string // materialized attach_notes (path -> content)
}
func (k *remoteKB) Search(ctx, q string) ([]agentruntime.Doc, error)         // SearchScoped
func (k *remoteKB) Read(ctx, path string) (string, error)                    // overlay first, else NoteScoped
func (k *remoteKB) Write(ctx, path, content string) error                    // updateNotes upsert
func (k *remoteKB) Patch(ctx, path, find, replace string) error              // updateNotes SURGICAL patch
var _ agentruntime.KB = (*remoteKB)(nil)

• attach_notes seeding: the overlay is populated from the payload's materialized notes — zero round-trips for in-band context. Reads of non-attached in-scope paths fall back to NoteScoped.
• Scoped token only: every IO uses k.token; the admin key is structurally unreachable from RemoteKB.
• Surgical write-back (Patch): routes to the updateNotes patch branch (find/replace) so unmodeled kanban card metadata is preserved. Requires the patch_note tool + AgentChange.Find/Replace/Kind="patch" addition in agentruntime (one coordinated runtime edit: update runtime.go, kb.go, scope.go, filekb.go, cmd/agent together, then re-freeze). Without this the demo only "passes" via lossy full rewrite — it misrepresents production.

Validation tests: overlay hit returns content with no client call; out-of-scope read denied by ScopedKB before any client call; Patch issues the find/replace updateNotes variant; spend (res.TokensUsed/Steps) flows into the HTTP response.

---

5c. trip2g minimal changes — transform_jsonnet, attach_notes, concurrency, attribution

Invariant: the egress path is unchanged. All five changes hang off the existing seams; trip2g never imports agentruntime.

(1) transform_jsonnet — outbound transform. New shared package, NOT a call into frontmatterpatch.Evaluate (which hardcodes meta/path ExtVars + shallow-merge — wrong for an arbitrary outbound body):

// internal/jsonneteval/jsonneteval.go — single MaxStack source of truth
func NewVM() *jsonnet.VM { vm := jsonnet.MakeVM(); vm.MaxStack = 500; return vm }
func EvalJSON(src string, extVars map[string]string) (json.RawMessage, error)
func Validate(src string, sampleExtVars map[string]string) error

Applied strictly between json.Marshal (resolve.go:101) and SignHMAC (:107) so the signature and the logged request_body both cover the transformed bytes:

if wh.TransformJsonnet != "" {
    out, terr := jsonneteval.EvalJSON(wh.TransformJsonnet, transformExtVars(payloadBytes))
    if terr != nil { // never send a half-built request
        handleDeliveryError(ctx, env, params,
            webhookutil.DeliveryResult{Err: fmt.Errorf("transform_jsonnet: %w", terr)}, wh)
        return nil
    }
    payloadBytes = out
}
signature := webhookutil.SignHMAC(payloadBytes, wh.Secret)

Security: transformExtVars exposes the change/attached-notes/meta — but NOT api_token and NOT secrets (the powerful credential and secret values are delivered via separate fields/headers the jsonnet cannot see, so they never reach the logged request_body). frontmatterpatch.NewVM is refactored to delegate to jsonneteval.NewVM; Evaluate untouched (its tests remain the guard). CRUD validates via jsonneteval.Validate → ErrorPayload on failure. Cron twin identical.

(2) attach_notes — gate + materialize.

// handlenotewebhooks.Resolve — presence GATE after matched non-empty (:159), before Insert (:169)
attach, _ := webhookutil.ParseJSONStringArray(wh.AttachNotes)
if !attachGateSatisfied(attach, nvs) { continue } // plain glob: require ≥1; "!glob": require 0

Delivery job materializes matched (non-!) notes into the payload as {path,title,content,updated_at,tags,meta} from model.NoteView (note.go:156). meta should be tags + a small allowlist, not full RawMeta (avoid leaking frontmatter the role didn't ask for).

(3) concurrency_mode — race-free no-overlap. All mutations run on the single serialized write connection → WHERE NOT EXISTS is atomic; no app lock:

-- name: InsertWebhookDeliveryIfClear :many
insert into change_webhook_deliveries (webhook_id, attempt, status)
select sqlc.arg(webhook_id), 1, 'pending'
where not exists (
  select 1 from change_webhook_deliveries
  where webhook_id = sqlc.arg(webhook_id)
    and status in ('pending','running')
    and coalesce(heartbeat_at, started_at, created_at) >= datetime('now', sqlc.arg(stale_window)))
returning *;          -- 0 rows => skipped

switch wh.ConcurrencyMode {
case "skip":      d, ok, _ := env.InsertWebhookDeliveryIfClear(ctx, wh.ID, staleWindow(wh), cooldown); if !ok { continue }
case "queue_one": d, ok, _ := env.InsertWebhookDeliveryIfNoPending(ctx, wh.ID); if !ok { continue }
default:          d, _ := env.InsertWebhookDelivery(ctx, ...) // allow_overlap = today
}

• 'running' status needs no DDL (status column has no CHECK, 20260209100000:32).
• MarkWebhookDeliveryRunning (status='running', started_at=now where id=? and status='pending') at job pickup.
• Stale predicate coalesce(heartbeat_at,started_at,created_at) self-heals a crashed-fleet running row.
• Janitor cron expirestalewebhookdeliveries finalizes orphans to failed (registered cmd/server/cronjobs.go:45).
• Demo cooldown = appconfig AgentDeliveryCooldownSeconds (no column).
• ⚠️ CRUD must validate the concurrency_mode enum before insert, else a raw SQLite CHECK error surfaces as nil,error ("Internal Error") instead of a clean ErrorPayload.

(4) Attribution + spend. The write-back is a separate updateNotes call authenticated by the scoped shortapitoken — which today produces a virtual api key ID 0 (checkapikey/resolve.go:135), so attribution is blind. Carry the delivery identity in the token and stamp it through the existing actor pipe:

// internal/shortapitoken/token.go
type Data struct {
    Depth         int      `json:"d"`
    ReadPatterns  []string `json:"rp"`
    WritePatterns []string `json:"wp"`
    DeliveryKind  string   `json:"dk,omitempty"` // "change" | "cron"
    DeliveryID    int64    `json:"di,omitempty"`
}
// internal/model/note_actor.go
type NoteActor struct { UserID *int64; APIKeyID *int64; Client *string; DeliveryKind *string; DeliveryID *int64 }
// internal/webhookutil/agentresponse.go
type AgentResponse struct { Status, Message string; Changes []AgentChange; TokensUsed, Steps int }

Chain (≈6 files, must land atomically or attribution is silently NULL): shortapitoken.Data → checkapikey.resolveShortAPIToken sets req.WebhookDeliveryKind/ID → appreq.Request+NewContext → NoteVersionActor (cmd/server/notes.go:116) → insertnote.Resolve → InsertNoteVersion (+make sqlc). (kind,id) because change/cron are two tables (mirrors webhook_delivery_logs). Spend: deliver*webhook parses AgentResponse.{TokensUsed,Steps} → UpdateWebhookDeliveryResult.

(5) THE SECURITY FIX — make the scope real. Critic-verified: WebhookReadPatterns/WritePatterns are set but have zero consumers — the scope is decorative server-side. Add enforcement:

// internal/case/updatenotes/resolve.go — for each change:
if wp := appreq.WebhookWritePatterns(ctx); len(wp) > 0 && !webhookutil.MatchesAny(path, wp) {
    return model.ErrorPayload("write denied for path: "+path), nil // validation -> ErrorPayload
}
// mirror in note(path:) / search resolvers for WebhookReadPatterns

This converts least-privilege from fiction to fact and closes the central security hole.

Narrow tests: jsonnet identity vs remap vs runtime-error→handleDeliveryError (no POST); HMAC over transformed bytes; empty column = byte-for-byte regression; attach gate truth table; concurrency table (allow/skip/queue_one × in-flight/stale/cooldown) + a two-concurrent-skip → exactly-one property; janitor (stale→failed, fresh→untouched, injected clock); attribution end-to-end (token → note_version row links to delivery); write-pattern enforcement: out-of-pattern write → ErrorPayload.

---

5d. Phase 2 — secrets under the new model

• trip2g-side secret resolution serves the transform_jsonnet outbound path + existing webhook secret (generalize the prefix+decrypt). Zero new tables — reuse secrets + ChangeWebhookSecretPrefix.
• The fleet's own LLM API key is fleet-local config, never a trip2g secret, never in a note/message/log.
• If an agent tool needs an authed external call, the fleet uses fleet-local config OR fetches materialized headers from a scoped trip2g endpoint — never the master key.
• Secret VALUES resolve server-side in trip2g and are kept out of the jsonnet ExtVar and the logged body (see §7).

// sketch — Phase 2 scoped header endpoint (no master key crosses the boundary)
func (c *Client) MaterializeHeaders(ctx, token, group string) (map[string]string, error) // POST /_system/graphql, scoped

Test: secret values never appear in request_body logs; fleet never receives the master key; header materialization is gated by the scoped token.

---