Vesper

intent

vesper is the system's daily voice, aggregating signals from every other skill into concise, conversational morning or evening briefings. it surfaces concrete outcomes, upcoming decisions, and actionable opportunities without exposing internal architecture or analysis processes. use vesper when you need a morning or evening briefing, want to check pending decisions, request an on-demand briefing, or configure the briefing schedule. do not use vesper for deep research (use Sift), pattern analysis (use Corvus), or message drafting (use Dispatch).

inputs

External connections:

• Corvus: reads InsightProposal files from /workspace/openclaw/data/ocas-corvus/proposals/ (cooperative read; Corvus owns output)
• Custodian: reads InsightProposal files from /workspace/openclaw/data/ocas-custodian/proposals/ for Tier 3/4 escalations (cooperative read)
• Dispatch: reads DispatchSummaryReport from /workspace/openclaw/data/ocas-dispatch/reports/YYYY-MM-DD-{period}.json for Messages section (cooperative read; Dispatch owns data)
• Rally: reads daily portfolio reports from /workspace/openclaw/data/ocas-rally/reports/YYYY-MM-DD-daily.json for Markets section (cooperative read)
• Vibes (optional): reads voice identity, channel rules, and anti-AI pattern references from ocas-vibes to shape briefing tone
• Google Calendar: reads event data for Today and Logistics sections
• Google Weather: reads current conditions, hourly forecasts, and weekend outlook
• Chronicle: reads entity data for person/event/place context (read-only reference)

Configuration:

• config.json at /workspace/openclaw/data/ocas-vesper/config.json with keys: schedule.morning_window (default "07:00-09:00"), schedule.evening_window (default "17:00-19:00"), schedule.timezone (default "America/Los_Angeles"), sections flags (all default true)
• Override times via vesper.config.set morning_hour <H> or vesper.config.set evening_hour <H>

Invocation modes:

• automatic morning: triggered by cron during configured morning window
• automatic evening: triggered by cron during configured evening window
• manual: on user request via vesper.briefing.manual

Context available at runtime:

• current date, time, timezone
• user identity (e.g., "Jared")
• user location (home vs. traveling, derived from calendar or explicit config)
• proposal_id values already processed (tracked in signals_evaluated.jsonl to prevent reprocessing)

procedure

Morning briefing generation (vesper.briefing.morning):

1. check if morning window is active (current time within schedule.morning_window). if outside window, log warning and stop. if forced (manual invocation), proceed.

2. read all InsightProposal files from /workspace/openclaw/data/ocas-corvus/proposals/ and /workspace/openclaw/data/ocas-custodian/proposals/. for each proposal, check proposal_id against signals_evaluated.jsonl. skip proposals already processed.

3. apply signal filtering rules: include actionable information, meaningful outcomes, plan-affecting changes, multi-signal opportunities, preparation-useful information. exclude routine background activity, already-experienced events, internal system reasoning, speculative observations. mark each proposal as "included" or "filtered" with reason. append consumed proposal_id values to signals_evaluated.jsonl.

4. fetch Google Calendar data for today and next 7 days (for Logistics section). fetch weather: current condition, 10am commute forecast, high, 4pm commute forecast, low. if friday, append weekend forecast line. apply location context: if user is traveling (detected from calendar itinerary or explicit location setting), prefix weather with location name ("here's what tokyo looks like today"); if at home, omit location callout.

5. read Dispatch summary from /workspace/openclaw/data/ocas-dispatch/reports/YYYY-MM-DD-morning.json if present. extract high_priority_threads, pending_followups, active_commitments for Messages section.

6. read Rally daily report from /workspace/openclaw/data/ocas-rally/reports/YYYY-MM-DD-daily.json if present. extract portfolio data for Markets section. format: "portfolio closed yesterday at $XXX,XXX (±X.X%)". surface notable movers only when movement is material (>2%).

7. build briefing sections in order: greeting (no punctuation: "good morning jared"), weather, Today (calendar events, deadlines), Messages (from Dispatch), Logistics (travel, location context), Markets (portfolio, notable movers), Decisions (unacted decision requests), System (anomalies from Custodian proposals). omit any section with no content (do not render empty sections or "nothing to report" placeholders).

8. apply formatting rules: plain text or minimal HTML suitable for Gmail. conversational paragraphs, not bullet dumps. section headers use monochrome extended characters (▪ Today, ✉ Messages, ⚑ Logistics, ◈ Markets, ⟡ Decisions, ⚙ System). links are inline (relevant words become anchor text; no trailing link labels). calendar events link to https://calendar.google.com/calendar/event?eid={event_id}, locations link to https://maps.google.com/?q={place+name+address}, message references link to https://mail.google.com/mail/u/0/#inbox/{thread_id}, tracking items link to status pages. normal-state system health is silence, not confirmation (no "no flags", "systems normal", "all clear").

9. if Vibes is present, apply voice guidance and anti-AI pattern rules to all briefing text. otherwise generate without voice guidance.

10. write briefing file to /workspace/openclaw/data/ocas-vesper/briefings/YYYY-WXX/YYYY-MM-DD-morning.json using VesperBriefingFile schema (see references/schemas.md). create week directory (ISO week format e.g. 2026-W14) if absent. include content, sections_rendered, signals_included, decisions_presented, entities_observed, timestamp, delivery_status.

11. append briefing record to /workspace/openclaw/data/ocas-vesper/briefings.jsonl with keys: date, type (morning/evening), sections_rendered, signal_count, decision_count, timestamp.

12. append evaluated signals to /workspace/openclaw/data/ocas-vesper/signals_evaluated.jsonl with keys: proposal_id, skill, decision, reason, timestamp.

13. for each decision request included in briefing, append to /workspace/openclaw/data/ocas-vesper/decisions_presented.jsonl with keys: decision_id, option, benefit, cost, presented_at, presented_in (morning/evening).

14. call vesper.journal to write Action Journal entry with entity observations (see journal outputs section).

15. log completion and return briefing file path to invoker.

Evening briefing generation (vesper.briefing.evening):

1-14. repeat morning procedure with these modifications:

• use schedule.evening_window for window check (default "17:00-19:00")
• read Dispatch summary from /workspace/openclaw/data/ocas-dispatch/reports/YYYY-MM-DD-evening.json
• weather: no past weather reporting; exclude summaries of meetings already attended
• markets format: "portfolio opened at $XXX,XXX and closed at $XXX,XXX (±X.X%)". surface notable movers only when material.
• write briefing to /workspace/openclaw/data/ocas-vesper/briefings/YYYY-WXX/YYYY-MM-DD-evening.json
• append to /workspace/openclaw/data/ocas-vesper/briefings.jsonl with type "evening"

On-demand briefing (vesper.briefing.manual):

1. accept optional type parameter (default "manual"). skip window check.
2. follow morning procedure (steps 2-15), but write to /workspace/openclaw/data/ocas-vesper/briefings/YYYY-WXX/YYYY-MM-DD-manual.json and record type as "manual" in JSONL files.

Check pending decisions (vesper.decisions.pending):

1. read /workspace/openclaw/data/ocas-vesper/decisions_presented.jsonl.
2. filter for records with presented_at in last 72 hours and no corresponding entry in decisions.jsonl with matching decision_id and status "acted".
3. return list as JSON array with keys: decision_id, option, benefit, cost, presented_at, days_pending.

Update configuration (vesper.config.set <key> <value>):

1. read /workspace/openclaw/data/ocas-vesper/config.json.
2. validate key (one of: morning_hour, evening_hour, timezone, sections.{section_name}, retention.days, retention.max_records).
3. validate value type (hours 0-23, timezone string from IANA list, booleans for sections, integers for retention).
4. update config.json, set updated_at timestamp, write back to disk.
5. if morning_hour or evening_hour changed, recalculate cron schedules and invoke openclaw cron update for affected jobs.
6. return confirmation: "updated {key} to {value}".

Show status (vesper.status):

1. read /workspace/openclaw/data/ocas-vesper/config.json and briefings.jsonl.
2. find most recent briefing entry (type morning, evening, or manual). extract timestamp and sections_rendered.
3. call vesper.decisions.pending to get unacted count.
4. return JSON object: last_briefing (timestamp, type, section_count), pending_decisions (count, list of decision_id), schedule (morning_window, evening_window, timezone).

Write journal (vesper.journal):

1. collect entities encountered during current run from briefing sections: Entity/Person (from calendar events, messages, task assignments), Concept/Event (meetings, due dates, travel departures), Place (meeting venues, travel destinations, weather locations).
2. for each entity, determine user_relevance: "user" (directly related to user's calendar, tasks, messages), "agent_only" (incidental context from external sources), "unknown" (unclear).
3. build Action Journal entry with payload keys: skill_id (ocas-vesper), run_type (morning/evening/manual), entities_observed (list with type, name, context, user_relevance), relationships_observed (e.g., person attending event, event at location), preferences_observed (sections engaged, decisions acted), signals_evaluated_count, decisions_presented_count, okr_metrics (signal_precision, terminology_compliance, decision_framing scores).
4. write to /workspace/openclaw/journals/ocas-vesper/YYYY-MM-DD/{run_id}.json (run_id is UUID). create directory if absent.
5. return journal file path.

Self-update (vesper.update):

1. read source: URL from skill frontmatter (should be https://github.com/indigokarasu/vesper).
2. read local version from skill.json (skill_version field).
3. fetch remote version from GitHub: gh api "repos/indigokarasu/vesper/contents/skill.json" --jq '.content' | base64 -d | python3 -c "import sys,json;print(json.load(sys.stdin)['version'])". set timeout to 10 seconds.
4. compare versions. if equal, stop silently.
5. download and install: create temp directory, fetch tarball from https://api.github.com/repos/indigokarasu/vesper/tarball/main, extract to temp directory, copy all files into skill directory, delete temp directory.
6. on failure, retry once. if second attempt fails, report error and stop (do not leave skill in partial state).
7. output exactly: "I updated Vesper from version {old} to {new}" (lowercase). output only on success or recoverable error.

Initialization (vesper.init):

1. create /workspace/openclaw/data/ocas-vesper/ and subdirectories: briefings/.
2. write default config.json with all ConfigBase fields if file absent. include timestamp fields created_at, updated_at.
3. create empty JSONL files if absent: briefings.jsonl, signals_evaluated.jsonl, decisions_presented.jsonl, decisions.jsonl.
4. create /workspace/openclaw/journals/ocas-vesper/ directory.
5. invoke openclaw cron list. check for jobs named vesper:morning, vesper:evening, vesper:update. for each absent, invoke openclaw cron add with exact parameters (see background tasks table below).
6. log initialization as DecisionRecord in decisions.jsonl: {"decision_id":"vesper-init-{timestamp}","action":"initialized","timestamp":"{iso_timestamp}","status":"acted"}.

decision points

window check for automatic briefing: if invocation is automatic (cron-triggered) and current time is outside configured window (morning_window or evening_window), log warning and stop. if invocation is manual (user-requested), skip window check and proceed.

proposal already processed: if proposal_id exists in signals_evaluated.jsonl with decision set to "included" or "filtered", skip reading and evaluating the proposal again. this prevents double-counting signals across runs.

dispatch data present: if DispatchSummaryReport exists at the expected path and timestamp is recent (within last 24 hours), read high_priority_threads, pending_followups, active_commitments and populate Messages section. if file absent or stale (>24 hours old), omit Messages section entirely.

rally data present: if Rally daily report exists at the expected path and timestamp is recent (within last 24 hours), extract portfolio data and populate Markets section. if file absent or stale, omit Markets section.

weather location context: if user calendar contains travel events with location data (flight, hotel, arrival/departure times), user is traveling. detect destination location from event. prefix weather narrative with location ("here's what tokyo looks like today"). if no travel events detected, user is at home. omit location callout and render weather without location prefix.

evening weather rules: exclude any historical weather data (past conditions, past forecasts). exclude summaries of calendar events already completed. surface only forward-looking forecasts and preparation-useful context.

vibes present: if ocas-vibes skill is installed and accessible, read voice config and anti-AI pattern references. apply voice guidance (lowercase, punchy, direct cadence) and anti-AI rules to all briefing text (no corporate hedging, no sycophancy, no marketing hype). if Vibes absent, generate briefing text without voice guidance (use default neutral technical voice).

decision request framing: for each decision request included in briefing, verify presence of option, benefit, and cost fields. frame decision as optional ("you could also consider X"). if any field missing, do not include decision in briefing (filter it out and note reason in signals_evaluated.jsonl).

empty sections: if a section has no content after filtering (e.g., no calendar events, no pending decisions), do not render that section header or placeholder text. omit the section entirely from briefing output.

normal system health: if system status is normal with no anomalies (no Custodian proposals, no Corvus alerts), do not include System section. silence on normal is the rule, not confirmation.

rate limit or timeout on external reads: if read from Corvus, Custodian, Dispatch, or Rally times out (>10 seconds) or returns 429 (rate limit), skip that data source. continue generating briefing with available data. log timeout event in signals_evaluated.jsonl with reason "timeout". do not fail the entire briefing.

config validation: when user invokes vesper.config.set, validate the key exists in config schema. validate value type (hours 0-23 integer, timezone string from IANA, boolean for section flags, positive integer for retention). if validation fails, return error message and do not modify config.json.

cron schedule update: if morning_hour or evening_hour config changes via vesper.config.set, recalculate cron schedule (e.g., morning_hour 6 = schedule "0 6 * * *"). invoke openclaw cron update --name vesper:morning --schedule "{new_schedule}" to propagate change.

output contract

Morning and evening briefings:

• output format: JSON file (VesperBriefingFile schema) written to /workspace/openclaw/data/ocas-vesper/briefings/YYYY-WXX/YYYY-MM-DD-{type}.json where type is "morning", "evening", or "manual". week directory must exist (ISO week format 2026-W14).
• JSON schema keys: content (string, plain text or minimal HTML), sections_rendered (array of section names present), signals_included (count), decisions_presented (array of decision_id), entities_observed (array with type, name, context, user_relevance), timestamp (ISO 8601), delivery_status (string, "pending_delivery" on creation).
• content rules: plain text or minimal HTML suitable for Gmail rendering (no markdown #, **, ---, ---). conversational paragraphs. section headers use extended characters (▪ Today, ✉ Messages, ⚑ Logistics, ◈ Markets, ⟡ Decisions, ⚙ System). links are inline (relevant words anchor; no trailing labels). greeting on first line: "good morning jared" or "good evening jared" (no period). weather as narrative prose with emoji before condition words. no internal system terminology, no architecture references, no speculative observations.
• signals included: actionable information, meaningful outcomes, plan-affecting changes, multi-signal opportunities, preparation-useful information. exclude routine background, already-experienced events, speculation.
• decision requests: each decision formatted as option, benefit, cost, framed as optional.

JSONL files:

• briefings.jsonl: append one record per briefing (morning, evening, manual). keys: date (YYYY-MM-DD), type, sections_rendered (array), signal_count, decision_count, timestamp.
• signals_evaluated.jsonl: append one record per evaluated proposal. keys: proposal_id, skill (source skill name), decision ("included" or "filtered"), reason (string), timestamp.
• decisions_presented.jsonl: append one record per decision included in briefing. keys: decision_id, option, benefit, cost, presented_at (ISO 8601), presented_in (morning/evening/manual).
• decisions.jsonl: append when user acts on a decision (inferred from subsequent briefings). keys: decision_id, action (text description), timestamp, status ("acted" or "ignored").

config.json:

• location: /workspace/openclaw/data/ocas-vesper/config.json
• format: JSON object with keys skill_id, skill_version, config_version, created_at, updated_at, schedule (morning_window, evening_window, timezone), sections (flags for today, messages, logistics, markets, decisions, system), retention (days, max_records).
• default values: morning_window "07:00-09:00", evening_window "17:00-19:00", timezone "America/Los_Angeles", all section flags true, retention 30 days / 10000 records.

Journal output:

• location: /workspace/openclaw/journals/ocas-vesper/YYYY-MM-DD/{run_id}.json where run_id is UUID.
• format: Action Journal entry per spec-ocas-journal.md. keys: skill_id, run_type, entities_observed (array with type, name, context, user_relevance), relationships_observed (array), preferences_observed (array), signals_evaluated_count, decisions_presented_count, okr_metrics (object with signal_precision, terminology_compliance, decision_framing float values 0-1).

Command responses:

• vesper.briefing.{morning|evening|manual}: return JSON {"briefing_path":"...", "timestamp":"...", "sections_count":N, "signal_count":N, "decision_count":N}.
• vesper.decisions.pending: return JSON {"pending_count":N, "decisions":[{"decision_id":"...","option":"...","benefit":"...","cost":"...","presented_at":"...","days_pending":N}]}.
• vesper.config.set: return JSON {"key":"...","value":"...","status":"updated"} or error JSON with status "error" and message.
• vesper.status: return JSON {"last_briefing":{"timestamp":"...","type":"...","section_count":N},"pending_decisions":{"count":N},"schedule":{"morning_window":"...","evening_window":"...","timezone":"..."}}.
• vesper.journal: return JSON {"journal_path":"...","timestamp":"...","entity_count":N}.
• vesper.update: return string "I updated Vesper from version X to Y" or "no update available" (silent; output only on change or error).

outcome signal

briefing delivery success:

• briefing file appears at expected path /workspace/openclaw/data/ocas-vesper/briefings/YYYY-WXX/YYYY-MM-DD-{type}.json within 5 seconds of command invocation.
• briefing content is non-empty (at least greeting + one section).
• briefing delivery_status is set to "pending_delivery".
• Dispatch picks up the briefing file within 60 seconds and reads its content (inferred from Dispatch pickup logs).
• user receives briefing in email or configured delivery channel within 5 minutes.

signal filtering success:

• signals_evaluated.jsonl grows with new proposal_id entries marked "included" or "filtered" with reasons.
• included signals appear in briefing content; filtered signals do not.
• no duplicate proposal_id values in signals_evaluated.jsonl (reprocessing check works).

decision presentation success:

• decisions_presented.jsonl grows with new decision records.
• each decision in briefing matches a record in decisions_presented.jsonl.
• decision contains all three fields: option, benefit, cost.
• framing is optional (e.g., "you could also consider").

configuration change success:

• vesper.config.set key value returns status "updated".
• config.json reflects new value on disk.
• if hour changed, next automatic briefing uses new schedule (e.g., morning window shifts).

pending decision check success:

• vesper.decisions.pending returns list of decision_id from last 72 hours not yet acted upon.
• decision list is empty if all presented decisions have been acted (entry in decisions.jsonl with status "acted").
• decision list is non-empty only if user has not yet responded to decision request.

journal write success:

• journal file appears at /workspace/openclaw/journals/ocas-vesper/YYYY-MM-DD/{run_id}.json within 2 seconds of briefing completion.
• journal contains entities_observed array with at least one entity (or empty array if no entities encountered).
• journal okr_metrics values are floats 0-1 (or null if unable to compute).

self-update success:

• vesper.update completes without error.
• local skill.json version field updated to match remote version.
• output string printed: "I updated Vesper from version X to Y".
• no output printed if versions already match.

failure modes (user sees):

• briefing generation timeout (>30 seconds): user receives error message "briefing generation timed out" and briefing is not written.
• missing external data (Dispatch, Rally absent): briefing generated without that section (not an error; silence on missing data).
• invalid config key: user receives error "invalid config key: {key}". no config change made.
• cron job not registered: user sees warning in status output "background job vesper:morning not active"; can manually invoke vesper.init to register.
• journal write failure: briefing is still delivered; journal error is logged but does not block delivery.