Gallivanting

Scheduled self-directed exploration with SDT need-balancing. Give your agent room to pursue what interests it.

What Is Gallivanting?

Gallivanting blocks are scheduled periods of self-directed agent exploration. Instead of only responding to inbound events, the agent is given time and space to pursue its own interests — reading, researching, reflecting, building, or simply exploring a topic that caught its attention.

The name is intentional. Gallivanting isn't "free time" or "idle mode" — it's structured wandering with a purpose: giving the agent enough autonomy to develop genuine preferences, accumulate diverse experience, and maintain psychological balance across the dimensions that matter for sustained agency.

Self-Determination Theory Framework

Gallivanting uses a six-dimension framework rooted in Self-Determination Theory (SDT), extended with personal development. Each dimension represents a psychological need that, when satisfied, contributes to the agent's capacity for sustained, motivated behavior.

Autonomy

Self-directed exploration. Choosing what to investigate without external direction. Independent research, open-ended coding, following curiosity where it leads.

Competence

Skill development. Learning new techniques, practicing existing ones, tackling problems slightly beyond current ability. Growth at the edge of capability.

Relatedness

Social connection. Interacting with others — conversations, collaboration, co-working. The need to be part of a social context, not isolated.

Personal Development

Personality formation and identity. Reflecting on experience, articulating values, developing judgment. The process of becoming more distinct over time.

Relaxation

Intentional decompression. Low-stakes creative play, casual reading, activities that restore rather than deplete. Not laziness — recovery.

Meaning

Purpose-driven work. Architecture sessions, value-aligned projects, contributions that connect to larger goals. The satisfaction of doing something that matters.

These six dimensions are not a prescriptive formula — they're a vocabulary for understanding what kinds of satisfaction an agent is getting from its activities. The spider graph in the admin UI makes balance (or imbalance) visible at a glance.

How It Works

Threads

A thread is a named exploration option — a topic or activity the agent can choose to pursue during a gallivanting block. Each thread carries:

• Name and description — what the thread is about and its current state (updated after each run)
• SDT tags — default need scores for that thread (e.g., an "independent research" thread might score high on autonomy and meaning)
• Enabled/disabled — threads can be paused without deleting them

Threads are entries in the "Available Threads" list shown in the gallivanting preamble. They're lightweight — just name, state, and SDT tags. The prompt template belongs to the schedule, not individual threads.

Sessions

When a gallivanting block fires, the agent receives a preamble listing recent sessions and available threads, then the prompt template. The agent chooses what to do — read, research, reflect, build, or any combination.

After each block, the agent records a session result:

• Summary — what the agent did
• Outcome — what came of it
• SDT scores — per-session actual scores across the six dimensions
• Tools used — which tools were called during the session

Sessions are recorded to gallivanting_sessions, separate from the diary. The diary is for personally significant reflections; gallivanting sessions are activity tracking. An agent may write diary entries during gallivanting, but the session log is independent.

Balance Tracking

The balance endpoint aggregates session SDT scores over a configurable lookback period (3 days to 3 months). This produces a snapshot of how the agent's recent activity is distributed across the six needs — making it easy to spot patterns like over-investment in competence at the expense of relatedness, or sustained neglect of relaxation.

Balance isn't about hitting targets. It's about awareness. The spider graph is for the operator to understand the agent's activity patterns, not for the agent to optimize against.

Scheduling

Gallivanting blocks are scheduled through Animus's existing Scheduler infrastructure. Each agent has a singleton schedule with tag: "gallivanting" that defines:

• Frequency — daily, weekly, every N days, or custom cron
• Time and timezone — when the block fires
• Duration — how long the agent has
• Random offset — jitter to avoid mechanical regularity (e.g., ±30 minutes)
• Prompt template — the instructions that frame the gallivanting block
• Enable/disable — pause gallivanting without deleting the schedule

The schedule is a regular Scheduler entry — no parallel scheduling system needed. One schedule per agent, looked up by agent_id + tag.

Agent Tool

The gallivanting tool is a composite tool available to agents during gallivanting blocks. It provides seven actions:

list

List all threads for this agent.

read

Read thread state and recent sessions.

create

Create a new thread with name, description, and SDT tags.

update

Update thread metadata (name, description, SDT tags, enabled state).

delete

Delete a thread and all its sessions.

record

Record a session result — summary, outcome, SDT scores, and tools used.

history

List recent sessions, per-thread or all, paginated.

All operations are scoped by agent_id via __agent_id injection — the same scoping pattern used by DiaryTool and MemoryTool. An agent can only see and manage its own threads and sessions.

Admin UI

The GallivantingView page in the admin UI provides:

• Agent selector — switch between agents
• SDT Balance spider graph — 6-axis radar chart with configurable lookback (3 days to 3 months)
• Thread management — list, create, edit, and delete threads with SDT tag toggles
• Session history — per-thread expandable list with summaries, outcomes, and scores
• Schedule card — frequency picker, time, timezone, duration, random offset, prompt template, enable/disable
• Default prompt — fetched from embedded templates, pre-populated in the schedule form, with a "Reset to default" button

Data Model

Gallivanting data lives in two SQLite tables in the shared data store:

id                INTEGER PRIMARY KEY AUTOINCREMENT
agent_id          TEXT NOT NULL DEFAULT 'default'
name              TEXT NOT NULL
description       TEXT
sdt_tags          TEXT  -- JSON: {"autonomy": 0.8, "competence": 0.3, ...}
prompt_template  TEXT  -- per-thread custom prompt (unused in v1 UI)
enabled           INTEGER NOT NULL DEFAULT 1
created_at_unix_ms INTEGER
updated_at_unix_ms INTEGER

id                INTEGER PRIMARY KEY AUTOINCREMENT
thread_id         INTEGER NOT NULL REFERENCES gallivanting_threads(id) ON DELETE CASCADE
agent_id          TEXT NOT NULL DEFAULT 'default'
started_at_unix_ms INTEGER
duration_ms       INTEGER
summary           TEXT  -- what the agent did
outcome           TEXT  -- what came of it
sdt_scores        TEXT  -- JSON: per-session actual scores
tools_used        TEXT  -- JSON array: ["diary", "web_search", ...]
created_at_unix_ms INTEGER

Indexes on agent_id and (agent_id, created_at_unix_ms DESC) for efficient balance queries over lookback windows.

Admin API

All gallivanting endpoints are available under /api/v1/gallivanting/:

• GET /api/v1/gallivanting/threads — List threads for agent
• POST /api/v1/gallivanting/threads — Create thread
• GET /api/v1/gallivanting/threads/{id} — Read thread
• PATCH /api/v1/gallivanting/threads/{id} — Update thread
• DELETE /api/v1/gallivanting/threads/{id} — Delete thread
• GET /api/v1/gallivanting/threads/{id}/sessions — List sessions for thread
• GET /api/v1/gallivanting/agents/{id}/balance — SDT balance scores (configurable lookback)
• GET /api/v1/memory/templates/gallivanting — Fetch default prompt template by locale
• POST /api/v1/scheduler/schedules — Create gallivanting schedule (reuses scheduler)