Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Activity Digest — daily-log auto-drafts (Human Activity Tracking Phase 6, #2155).
*
* Summarizes a day's Human Activity timeline (conversations, meetings, media
* consumed — with tribe-person names resolved) into a compact draft, then
* splices it as a clearly-marked auto-generated section into that day's Brain
* daily-log entry (via brainJournal.upsertAutoSection → federates + re-embeds).
*
* Two modes:
* 1. Non-LLM (always available, zero provider calls). `formatActivityDigest`
* renders a deterministic structured bullet list — useful on its own AND
* the template fed to the LLM.
* 2. LLM narrative (opt-in). Only when a provider is configured in settings —
* the config UI names the provider/model. See "AI Provider Usage Policy" in
* AGENTS.md: the feature is silent until the user enables it, and the
* scheduled run is a sanctioned automation the user set up.
*
* The scheduler lives in activityDigestScheduler.js; the manual "draft today
* now" button hits POST /brain/daily-log/:date/draft (a direct user action).
*/
import { join } from 'path';
import { PATHS } from '../lib/fileUtils.js';
import { createSettingsStore } from '../lib/settingsStore.js';
import { buildMarkers } from '../lib/markedSection.js';
import { getUserTimezone } from './userTimezone.js';
import { getDaySummary } from './humanActivity.js';
import * as journal from './brainJournal.js';
import { getPerson } from './tribe.js';
import { getProviderById } from './providers.js';
import { runPromptThroughProvider } from './promptRunner.js';
import { isToolFreeOneShotProvider } from '../lib/providerVendors.js';
const SETTINGS_FILE = join(PATHS.brain, 'activity-digest-settings.json');
// Stable marker pair — a re-run replaces ONLY this region in the journal entry.
export const DIGEST_MARKERS = buildMarkers('activity-digest');
const DEFAULT_SETTINGS = {
// Scheduler opt-in. When false the feature is entirely silent — no scheduled
// runs, no provider calls (the manual "draft now" button still works).
enabled: false,
// LLM provider/model for the narrative. null → non-LLM bullets only (zero
// provider calls). The config UI names whichever provider/model is set here.
provider: null,
model: null,
// Evening local time (HH:MM, user's timezone) the scheduled draft runs.
runTime: '21:00',
// How many prior days a missed-run catch-up will backfill (0 = today only).
catchUpDays: 3,
// Managed server-side — the last day successfully drafted + when.
lastRunDate: null,
lastRunAt: null,
};
// Keys the client may write via PUT — managed fields (lastRun*) are stripped.
const CLIENT_SETTABLE = ['enabled', 'provider', 'model', 'runTime', 'catchUpDays'];
// ─── Settings ────────────────────────────────────────────────────────────────
// Strict read + serialized PATCH live in the store (#4115): a corrupt file
// rejects instead of reading as DEFAULT_SETTINGS and being overwritten.
const settingsStore = createSettingsStore(SETTINGS_FILE, DEFAULT_SETTINGS);
export const getSettings = settingsStore.get;
// Persist a partial update. Only client-settable keys are honored from
// `partial`; `internal` carries server-managed fields (lastRunDate/lastRunAt).
export async function updateSettings(partial = {}, internal = {}) {
return settingsStore.update({
...Object.fromEntries(CLIENT_SETTABLE.map((key) => [key, partial[key]])),
lastRunDate: internal.lastRunDate,
lastRunAt: internal.lastRunAt,
});
}
// ─── Pure helpers (exported for unit tests — no I/O) ─────────────────────────
const CONVERSATION_KINDS = new Set(['message.sent', 'message.received']);
const MEETING_KINDS = new Set(['calendar.event']);
const MEDIA_KINDS = new Set(['media.listen', 'media.watch']);
const isoRe = /^\d{4}-\d{2}-\d{2}$/;
const isIso = (d) => typeof d === 'string' && isoRe.test(d);
// Shift a YYYY-MM-DD string by N days (UTC math — the string is a calendar day,
// not an instant, so DST doesn't apply). Returns YYYY-MM-DD.
export function shiftIso(date, days) {
const [y, m, d] = date.split('-').map(Number);
const dt = new Date(Date.UTC(y, m - 1, d));
dt.setUTCDate(dt.getUTCDate() + days);
return dt.toISOString().slice(0, 10);
}
/**
* Which calendar days are due for a draft, given the last-drafted day and the
* catch-up window. Returns an ascending list of YYYY-MM-DD (always includes
* `today` when it hasn't been drafted yet — the scheduler decides today's
* time-of-day gate separately). Pure + timezone-agnostic (operates on the
* already-resolved local `today`).
*
* - never run → [today - catchUpDays … today]
* - last run == today → [] (nothing due; re-draft is idempotent)
* - last run == earlier → [max(lastRun+1, today-catchUpDays) … today]
*/
export function computeCatchUpDates(settings, today) {
if (!isIso(today)) return [];
const catchUpDays = Number.isFinite(settings?.catchUpDays)
? Math.max(0, Math.floor(settings.catchUpDays))
: 0;
const earliest = shiftIso(today, -catchUpDays);
let cursor;
if (isIso(settings?.lastRunDate)) {
const dayAfterLast = shiftIso(settings.lastRunDate, 1);
cursor = dayAfterLast > earliest ? dayAfterLast : earliest;
} else {
cursor = earliest;
}
const dates = [];
// `cursor > today` guards against a lastRunDate in the future (clock skew).
while (cursor <= today && dates.length <= catchUpDays + 1) {
dates.push(cursor);
cursor = shiftIso(cursor, 1);
}
return dates;
}
// Resolve a participant to a display name, preferring an explicit name, then a
// tribe-resolved name (nameByPersonId), then email/phone. Returns null when the
// participant has nothing usable.
function resolveParticipantName(p, nameByPersonId) {
if (!p) return null;
if (p.name) return p.name;
if (p.personId && nameByPersonId[p.personId]) return nameByPersonId[p.personId];
return p.email || p.phone || null;
}
// Unique, order-preserving list of participant display names across events.
function collectNames(events, nameByPersonId) {
const seen = new Set();
const names = [];
for (const ev of events) {
for (const p of ev.participants || []) {
const name = resolveParticipantName(p, nameByPersonId);
if (name && !seen.has(name)) {
seen.add(name);
names.push(name);
}
}
}
return names;
}
const joinNames = (names, max = 8) => (
names.length <= max
? names.join(', ')
: `${names.slice(0, max).join(', ')} +${names.length - max} more`
);
/**
* Render a day's activity into a deterministic Markdown bullet summary — the
* non-LLM fallback mode AND the template fed to the LLM. Returns null when the
* day has no tracked events (so callers skip writing an empty section).
*
* @param {object} daySummary — shape from humanActivity.getDaySummary()
* @param {object} [opts]
* @param {Record<string,string>} [opts.nameByPersonId] — personId → tribe name
*/
export function formatActivityDigest(daySummary, { nameByPersonId = {} } = {}) {
const events = Array.isArray(daySummary?.events) ? daySummary.events : [];
if (events.length === 0) return null;
const conversations = events.filter((e) => CONVERSATION_KINDS.has(e.kind));
const meetings = events.filter((e) => MEETING_KINDS.has(e.kind));
const media = events.filter((e) => MEDIA_KINDS.has(e.kind));
const lines = [];
if (conversations.length) {
const sent = conversations.filter((e) => e.kind === 'message.sent').length;
const received = conversations.length - sent;
const names = collectNames(conversations, nameByPersonId);
const withWhom = names.length ? ` with ${joinNames(names)}` : '';
lines.push(`**Conversations** — ${conversations.length} message${conversations.length === 1 ? '' : 's'} (${sent} sent, ${received} received)${withWhom}`);
}
if (meetings.length) {
lines.push(`**Meetings** — ${meetings.length}`);
for (const ev of meetings) {
const names = collectNames([ev], nameByPersonId);
const withWhom = names.length ? ` (with ${joinNames(names, 5)})` : '';
lines.push(`- ${ev.title || '(untitled event)'}${withWhom}`);
}
}
if (media.length) {
lines.push(`**Media** — ${media.length}`);
for (const ev of media) {
const verb = ev.kind === 'media.watch' ? 'Watched' : 'Listened';
const detail = ev.summary ? ` — ${ev.summary}` : '';
lines.push(`- ${verb}: ${ev.title || '(untitled)'}${detail}`);
}
}
// Anything that isn't a known category still counts as activity — summarize a
// tail count so the draft never silently drops events.
const known = conversations.length + meetings.length + media.length;
const other = events.length - known;
if (other > 0) {
lines.push(`**Other activity** — ${other} event${other === 1 ? '' : 's'}`);
}
return lines.join('\n');
}
// Wrap the section body with a visible header (rendered inside the markers). The
// header names the mode so the user can tell an LLM draft from raw bullets.
function buildSectionBody(date, body, { usedLlm }) {
const badge = usedLlm ? 'AI-drafted' : 'auto-summary';
return `### 🗓️ Activity Digest — ${date}\n_${badge} from your activity timeline. Edits above this line are preserved; this section is regenerated on each draft._\n\n${body}`;
}
// Build the LLM prompt from the non-LLM bullet template.
function buildNarrativePrompt(template, date) {
return [
'You are writing a brief first-person journal entry summarizing my day, based ONLY on the structured activity summary below.',
'Write 2–4 short sentences in past tense, first person ("I ..."). Be factual — do not invent people, events, or details not present in the summary. Do not add a heading or a preamble.',
'',
`Date: ${date}`,
'',
'Structured activity summary:',
template,
].join('\n');
}
// ─── Orchestration ───────────────────────────────────────────────────────────
// Build a personId → display-name map by resolving tribe people for the
// personIds present in the day's events. Best-effort: a lookup failure just
// leaves that id unresolved (formatter falls back to name/email/phone).
async function buildNameMap(events) {
const ids = new Set();
for (const ev of events) {
for (const p of ev.participants || []) {
// Only resolve ids we actually need — a participant that already carries a
// name doesn't need a tribe round-trip.
if (p?.personId && !p?.name) ids.add(p.personId);
}
}
const map = {};
for (const id of ids) {
const person = await getPerson(id).catch(() => null);
if (person?.name) map[id] = person.name;
}
return map;
}
// Generate the LLM narrative from the bullet template. Returns `{ text: null }`
// on any failure (caller falls back to the non-LLM bullets), plus `skipped`
// when the configured provider is refused outright. Never throws — runs on
// the scheduler path too.
async function generateNarrative(template, date, settings) {
const provider = await getProviderById(settings.provider).catch(() => null);
if (!provider || !provider.enabled) return { text: null };
// The template quotes other people's text (calendar invite titles, message
// participant names, media titles) and runs unattended on the scheduler, so
// it never reaches host tools: only a provider that can run it tool-free
// drafts the narrative, pinned so no fallback swaps in an agent harness.
if (!isToolFreeOneShotProvider(provider)) {
console.warn(`⚠️ Activity digest ${date}: provider ${provider.id} cannot run tool-free — keeping the bullet digest`);
return { text: null, skipped: 'provider-not-tool-free' };
}
const model = settings.model || provider.defaultModel;
// Headless classification-style run — append headlessArgs so a CLI provider
// doesn't persist a session transcript for the draft.
const providerForCall = provider.headlessArgs?.length
? { ...provider, args: [...(provider.args || []), ...provider.headlessArgs] }
: provider;
const result = await runPromptThroughProvider({
provider: providerForCall,
prompt: buildNarrativePrompt(template, date),
source: 'activity-digest',
model,
toolFree: true,
allowFallback: false,
}).catch((err) => {
console.error(`🗓️ Activity digest LLM narrative failed for ${date}: ${err.message}`);
return null;
});
const text = (result?.text || '').trim();
return { text: text || null };
}
/**
* Draft (or re-draft) the activity digest for one calendar day and splice it
* into that day's Brain daily-log entry. Idempotent — re-runs replace only the
* marked auto section, never user content.
*
* @param {string} date — YYYY-MM-DD
* @param {object} [opts]
* @param {boolean} [opts.recordRun=false] — stamp settings.lastRun* on success
* (the scheduler sets this; manual drafts don't move the scheduler cursor).
* @returns {Promise<{ date, drafted: boolean, usedLlm: boolean, reason?: string, narrativeSkipped?: string }>}
* `narrativeSkipped: 'provider-not-tool-free'` names why a configured
* provider drafted no narrative, so the UI can say so.
*/
export async function runDigestForDate(date, { recordRun = false } = {}) {
if (!journal.isIsoDate(date)) throw new Error(`invalid date: ${date}`);
const started = Date.now();
const settings = await getSettings();
const daySummary = await getDaySummary({ date });
const events = daySummary?.events || [];
const template = formatActivityDigest(daySummary, {
nameByPersonId: await buildNameMap(events),
});
if (!template) {
console.log(`🗓️ Activity digest ${date}: no tracked activity — nothing to draft`);
// Clear a stale auto section from a previous draft if the day is now empty.
await journal.upsertAutoSection(date, '', DIGEST_MARKERS);
if (recordRun) await stampRun(date);
return { date, drafted: false, usedLlm: false, reason: 'no-activity' };
}
let sectionBody = template;
let usedLlm = false;
let narrativeSkipped = null;
if (settings.provider) {
const { text: narrative, skipped } = await generateNarrative(template, date, settings);
narrativeSkipped = skipped || null;
if (narrative) {
// Prose narrative on top; keep the structured bullets beneath it for
// provenance / at-a-glance scanning.
sectionBody = `${narrative}\n\n${template}`;
usedLlm = true;
}
}
await journal.upsertAutoSection(date, buildSectionBody(date, sectionBody, { usedLlm }), DIGEST_MARKERS);
if (recordRun) await stampRun(date);
console.log(`🗓️ Activity digest drafted ${date} (${events.length} event(s), ${usedLlm ? 'LLM' : 'non-LLM'}) in ${Date.now() - started}ms`);
return { date, drafted: true, usedLlm, ...(narrativeSkipped ? { narrativeSkipped } : {}) };
}
// Advance the scheduler cursor to the drafted day.
async function stampRun(date) {
await updateSettings({}, { lastRunDate: date, lastRunAt: new Date().toISOString() });
}