clementine-agent 1.0.99 → 1.1.1

package/dist/config/clementine-json.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Clementine JSON config loader.
+ *
+ * `~/.clementine/clementine.json` is the canonical user-editable config file.
+ * Each field is optional — missing values fall through to .env, then to
+ * compiled defaults. Precedence (highest first):
+ *
+ *   1. process.env (CI/runtime overrides)
+ *   2. ~/.clementine/.env (existing user-edited config)
+ *   3. ~/.clementine/clementine.json (this file)
+ *   4. Compiled defaults
+ *
+ * The file is created on first run by the 0005 migration (kind: 'config').
+ * Loader validates with zod and falls back gracefully on malformed input —
+ * a corrupt file is logged and treated as empty.
+ *
+ * Cached by mtime so subsequent reads are O(1) absent file changes.
+ */
+import { z } from 'zod';
+export declare const clementineJsonSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ownerName: z.ZodOptional<z.ZodString>;
+    assistantName: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    models: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+        haiku: z.ZodOptional<z.ZodString>;
+        sonnet: z.ZodOptional<z.ZodString>;
+        opus: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    budgets: z.ZodOptional<z.ZodObject<{
+        heartbeat: z.ZodOptional<z.ZodNumber>;
+        cronT1: z.ZodOptional<z.ZodNumber>;
+        cronT2: z.ZodOptional<z.ZodNumber>;
+        chat: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    heartbeat: z.ZodOptional<z.ZodObject<{
+        intervalMinutes: z.ZodOptional<z.ZodNumber>;
+        activeStart: z.ZodOptional<z.ZodNumber>;
+        activeEnd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    unleashed: z.ZodOptional<z.ZodObject<{
+        phaseTurns: z.ZodOptional<z.ZodNumber>;
+        defaultMaxHours: z.ZodOptional<z.ZodNumber>;
+        maxPhases: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClementineJson = z.infer<typeof clementineJsonSchema>;
+export declare function clementineJsonPath(baseDir: string): string;
+/**
+ * Load and validate clementine.json. Returns an empty object if the file
+ * is missing, unreadable, or fails validation. Cached by mtime.
+ */
+export declare function loadClementineJson(baseDir: string): ClementineJson;
+/** Test-only: clear the loader cache. */
+export declare function _resetClementineJsonCache(): void;
+//# sourceMappingURL=clementine-json.d.ts.map

package/dist/config/clementine-json.js

@@ -0,0 +1,95 @@
+/**
+ * Clementine JSON config loader.
+ *
+ * `~/.clementine/clementine.json` is the canonical user-editable config file.
+ * Each field is optional — missing values fall through to .env, then to
+ * compiled defaults. Precedence (highest first):
+ *
+ *   1. process.env (CI/runtime overrides)
+ *   2. ~/.clementine/.env (existing user-edited config)
+ *   3. ~/.clementine/clementine.json (this file)
+ *   4. Compiled defaults
+ *
+ * The file is created on first run by the 0005 migration (kind: 'config').
+ * Loader validates with zod and falls back gracefully on malformed input —
+ * a corrupt file is logged and treated as empty.
+ *
+ * Cached by mtime so subsequent reads are O(1) absent file changes.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { z } from 'zod';
+const logger = pino({ name: 'clementine.config-json' });
+// ── Schema ───────────────────────────────────────────────────────────
+export const clementineJsonSchema = z.object({
+    schemaVersion: z.literal(1),
+    ownerName: z.string().optional(),
+    assistantName: z.string().optional(),
+    timezone: z.string().optional(),
+    models: z.object({
+        default: z.string().optional(),
+        haiku: z.string().optional(),
+        sonnet: z.string().optional(),
+        opus: z.string().optional(),
+    }).optional(),
+    budgets: z.object({
+        heartbeat: z.number().nonnegative().optional(),
+        cronT1: z.number().nonnegative().optional(),
+        cronT2: z.number().nonnegative().optional(),
+        chat: z.number().nonnegative().optional(),
+    }).optional(),
+    heartbeat: z.object({
+        intervalMinutes: z.number().int().positive().optional(),
+        activeStart: z.number().int().min(0).max(23).optional(),
+        activeEnd: z.number().int().min(0).max(23).optional(),
+    }).optional(),
+    unleashed: z.object({
+        phaseTurns: z.number().int().positive().optional(),
+        defaultMaxHours: z.number().positive().optional(),
+        maxPhases: z.number().int().positive().optional(),
+    }).optional(),
+});
+const cache = new Map();
+export function clementineJsonPath(baseDir) {
+    return path.join(baseDir, 'clementine.json');
+}
+/**
+ * Load and validate clementine.json. Returns an empty object if the file
+ * is missing, unreadable, or fails validation. Cached by mtime.
+ */
+export function loadClementineJson(baseDir) {
+    const filePath = clementineJsonPath(baseDir);
+    if (!existsSync(filePath))
+        return { schemaVersion: 1 };
+    let mtime;
+    try {
+        mtime = statSync(filePath).mtimeMs;
+    }
+    catch {
+        return { schemaVersion: 1 };
+    }
+    const cached = cache.get(filePath);
+    if (cached && cached.mtime === mtime)
+        return cached.data;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to parse clementine.json — using empty config');
+        return { schemaVersion: 1 };
+    }
+    const parsed = clementineJsonSchema.safeParse(raw);
+    if (!parsed.success) {
+        logger.warn({ filePath, errors: parsed.error.issues.slice(0, 3) }, 'clementine.json failed validation — using empty config');
+        return { schemaVersion: 1 };
+    }
+    cache.set(filePath, { mtime, data: parsed.data });
+    return parsed.data;
+}
+/** Test-only: clear the loader cache. */
+export function _resetClementineJsonCache() {
+    cache.clear();
+}
+//# sourceMappingURL=clementine-json.js.map

package/dist/config.js

@@ -76,9 +76,25 @@ export const PROJECTS_META_FILE = path.join(BASE_DIR, 'projects.json');
 export const WORKING_MEMORY_FILE = path.join(BASE_DIR, 'working-memory.md');
 export const IDENTITY_FILE = path.join(SYSTEM_DIR, 'IDENTITY.md');
 // ── Assistant identity ───────────────────────────────────────────────
-export const ASSISTANT_NAME = getEnv('ASSISTANT_NAME', 'Clementine');
+// JSON config — loaded once at module init. Lower precedence than .env.
+import { loadClementineJson } from './config/clementine-json.js';
+const json = loadClementineJson(BASE_DIR);
+/**
+ * Resolve a value with full precedence: process.env > .env > clementine.json > default.
+ * `getEnv` already covers the first two (process.env wins inside getEnv), so this
+ * helper just adds JSON as a fallback before the hardcoded default.
+ */
+function getEnvOrJson(envKey, jsonValue, fallback) {
+    const fromEnv = getEnv(envKey, '');
+    if (fromEnv)
+        return fromEnv;
+    if (jsonValue)
+        return jsonValue;
+    return fallback;
+}
+export const ASSISTANT_NAME = getEnvOrJson('ASSISTANT_NAME', json.assistantName, 'Clementine');
 export const ASSISTANT_NICKNAME = getEnv('ASSISTANT_NICKNAME', 'Clemmy');
-export const OWNER_NAME = getEnv('OWNER_NAME');
+export const OWNER_NAME = getEnvOrJson('OWNER_NAME', json.ownerName, '');
 // ── Secrets (with macOS Keychain fallback) ───────────────────────────
 export function shellEscape(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
@@ -197,7 +213,7 @@ export const SF_API_VERSION = getEnv('SF_API_VERSION', 'v62.0');
 export const ALLOW_ALL_USERS = getEnv('ALLOW_ALL_USERS', 'false').toLowerCase() === 'true';
 // ── Timezone ─────────────────────────────────────────────────────────
 /** User-configurable timezone. Falls back to system-detected timezone. */
-export const TIMEZONE = getEnv('TIMEZONE') || Intl.DateTimeFormat().resolvedOptions().timeZone;
+export const TIMEZONE = getEnvOrJson('TIMEZONE', json.timezone, Intl.DateTimeFormat().resolvedOptions().timeZone);
 // ── Heartbeat ────────────────────────────────────────────────────────
 export const HEARTBEAT_INTERVAL_MINUTES = parseInt(getEnv('HEARTBEAT_INTERVAL_MINUTES', '30'), 10) || 30;
 export const HEARTBEAT_ACTIVE_START = parseInt(getEnv('HEARTBEAT_ACTIVE_START', '8'), 10);

package/dist/vault-migrations/0004-backfill-schema-versions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Migration 0004: Backfill `schemaVersion: 1` into CRON.md and agent.md frontmatter.
+ *
+ * First multi-target migration — uses the new MigrationContext shape
+ * shipped in Phase 7a. Establishes the convention so future format changes
+ * (a v2 migration) can target files known to be at v1.
+ *
+ * Idempotent: parses with gray-matter, only writes when schemaVersion is
+ * missing or not equal to 1.
+ */
+import type { Migration } from './types.js';
+export declare const migration: Migration;
+//# sourceMappingURL=0004-backfill-schema-versions.d.ts.map

package/dist/vault-migrations/0004-backfill-schema-versions.js

@@ -0,0 +1,85 @@
+/**
+ * Migration 0004: Backfill `schemaVersion: 1` into CRON.md and agent.md frontmatter.
+ *
+ * First multi-target migration — uses the new MigrationContext shape
+ * shipped in Phase 7a. Establishes the convention so future format changes
+ * (a v2 migration) can target files known to be at v1.
+ *
+ * Idempotent: parses with gray-matter, only writes when schemaVersion is
+ * missing or not equal to 1.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+function backfillFile(filePath) {
+    if (!existsSync(filePath))
+        return 'missing';
+    let parsed;
+    try {
+        parsed = matter(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return 'invalid';
+    }
+    const data = (parsed.data ?? {});
+    if (data.schemaVersion === 1)
+        return 'already-set';
+    data.schemaVersion = 1;
+    // gray-matter's stringify preserves the original frontmatter style.
+    writeFileSync(filePath, matter.stringify(parsed.content, data));
+    return 'updated';
+}
+function findAgentMdFiles(vaultDir) {
+    const out = [];
+    const agentsDir = path.join(vaultDir, '00-System', 'agents');
+    if (!existsSync(agentsDir))
+        return out;
+    for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = path.join(agentsDir, entry.name, 'agent.md');
+        if (existsSync(candidate))
+            out.push(candidate);
+    }
+    return out;
+}
+export const migration = {
+    kind: 'vault',
+    id: '0004-backfill-schema-versions',
+    description: 'Backfill schemaVersion: 1 into CRON.md and agent.md frontmatter',
+    apply(ctx) {
+        const targets = [];
+        const cronPath = path.join(ctx.vaultDir, '00-System', 'CRON.md');
+        if (existsSync(cronPath))
+            targets.push(cronPath);
+        targets.push(...findAgentMdFiles(ctx.vaultDir));
+        if (targets.length === 0) {
+            return { applied: false, skipped: true, details: 'No CRON.md or agent.md files found' };
+        }
+        const stats = { updated: 0, alreadySet: 0, invalid: 0, missing: 0 };
+        for (const f of targets) {
+            const r = backfillFile(f);
+            if (r === 'updated')
+                stats.updated++;
+            else if (r === 'already-set')
+                stats.alreadySet++;
+            else if (r === 'invalid')
+                stats.invalid++;
+            else
+                stats.missing++;
+        }
+        if (stats.updated === 0) {
+            return {
+                applied: false,
+                skipped: true,
+                details: `All ${targets.length} files already have schemaVersion (alreadySet=${stats.alreadySet}, invalid=${stats.invalid})`,
+            };
+        }
+        return {
+            applied: true,
+            skipped: false,
+            details: `Updated ${stats.updated}/${targets.length} files (alreadySet=${stats.alreadySet}, invalid=${stats.invalid})`,
+        };
+    },
+};
+//# sourceMappingURL=0004-backfill-schema-versions.js.map

package/dist/vault-migrations/0005-create-clementine-json.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Migration 0005: Create ~/.clementine/clementine.json with sane defaults.
+ *
+ * First config-kind migration — uses MigrationContext.baseDir, not vaultDir.
+ * Reads the existing .env (already loaded into process at module init via
+ * config.ts, so we re-read here to be safe) and writes the equivalent
+ * canonical config file with comments explaining precedence rules.
+ *
+ * Idempotent: skips entirely if the file already exists. Users who edit
+ * the file post-migration are not at risk of having their edits overwritten.
+ */
+import type { Migration } from './types.js';
+export declare const migration: Migration;
+//# sourceMappingURL=0005-create-clementine-json.d.ts.map

package/dist/vault-migrations/0005-create-clementine-json.js

@@ -0,0 +1,133 @@
+/**
+ * Migration 0005: Create ~/.clementine/clementine.json with sane defaults.
+ *
+ * First config-kind migration — uses MigrationContext.baseDir, not vaultDir.
+ * Reads the existing .env (already loaded into process at module init via
+ * config.ts, so we re-read here to be safe) and writes the equivalent
+ * canonical config file with comments explaining precedence rules.
+ *
+ * Idempotent: skips entirely if the file already exists. Users who edit
+ * the file post-migration are not at risk of having their edits overwritten.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** Re-parse .env independently of config.ts's module-level cache. */
+function readEnv(baseDir) {
+    const envPath = path.join(baseDir, '.env');
+    if (!existsSync(envPath))
+        return {};
+    const result = {};
+    for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex);
+        let value = trimmed.slice(eqIndex + 1);
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function num(v) {
+    if (v === undefined || v === '')
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+export const migration = {
+    kind: 'config',
+    id: '0005-create-clementine-json',
+    description: 'Create clementine.json with current effective config as defaults',
+    apply(ctx) {
+        const targetPath = path.join(ctx.baseDir, 'clementine.json');
+        if (existsSync(targetPath)) {
+            return { applied: false, skipped: true, details: 'clementine.json already exists' };
+        }
+        const env = readEnv(ctx.baseDir);
+        // Build the canonical JSON. Only include fields we actually have values
+        // for — empty/missing fields are omitted so the file documents what was
+        // explicitly configured (not a wall of nulls).
+        const out = { schemaVersion: 1 };
+        if (env['OWNER_NAME'])
+            out.ownerName = env['OWNER_NAME'];
+        if (env['ASSISTANT_NAME'])
+            out.assistantName = env['ASSISTANT_NAME'];
+        if (env['TIMEZONE'])
+            out.timezone = env['TIMEZONE'];
+        const models = {};
+        if (env['DEFAULT_MODEL_TIER'])
+            models.default = env['DEFAULT_MODEL_TIER'];
+        if (env['HAIKU_MODEL'])
+            models.haiku = env['HAIKU_MODEL'];
+        if (env['SONNET_MODEL'])
+            models.sonnet = env['SONNET_MODEL'];
+        if (env['OPUS_MODEL'])
+            models.opus = env['OPUS_MODEL'];
+        if (Object.keys(models).length > 0)
+            out.models = models;
+        const budgets = {};
+        const bH = num(env['BUDGET_HEARTBEAT_USD']);
+        const bT1 = num(env['BUDGET_CRON_T1_USD']);
+        const bT2 = num(env['BUDGET_CRON_T2_USD']);
+        const bC = num(env['BUDGET_CHAT_USD']);
+        if (bH !== undefined)
+            budgets.heartbeat = bH;
+        if (bT1 !== undefined)
+            budgets.cronT1 = bT1;
+        if (bT2 !== undefined)
+            budgets.cronT2 = bT2;
+        if (bC !== undefined)
+            budgets.chat = bC;
+        if (Object.keys(budgets).length > 0)
+            out.budgets = budgets;
+        // Write as JSON with a leading comment-as-docstring isn't valid JSON.
+        // Instead we ship a sibling README that explains, and keep the JSON pure.
+        const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(out, null, 2) + '\n');
+        renameSync(tmp, targetPath);
+        // Also ship a README.md sibling explaining what this file is.
+        const readmePath = path.join(ctx.baseDir, 'README.md');
+        if (!existsSync(readmePath)) {
+            writeFileSync(readmePath, [
+                '# ~/.clementine/',
+                '',
+                'This is your Clementine data home. Updates to the engine (`npm update -g clementine-agent`)',
+                'replace the engine code but never touch this directory.',
+                '',
+                '## Editable config files',
+                '',
+                '- `clementine.json` — canonical user config (created by migration 0005)',
+                '- `.env` — secrets and per-machine overrides; takes precedence over `clementine.json`',
+                '- `vault/00-System/CRON.md` — cron jobs (YAML frontmatter)',
+                '- `vault/00-System/SOUL.md` — assistant personality / values',
+                '- `vault/00-System/agents/<slug>/agent.md` — per-agent definitions',
+                '- `advisor-rules/user/*.yaml` — custom advisor rules (overrides shipped builtins)',
+                '- `prompt-overrides/{_global.md,jobs/<name>.md,agents/<slug>.md}` — prompt augmentation',
+                '',
+                '## Config precedence (highest first)',
+                '',
+                '1. `process.env` — runtime overrides',
+                '2. `.env` in this dir — explicit per-machine config',
+                '3. `clementine.json` — canonical config',
+                '4. Compiled defaults',
+                '',
+                '## State and cache',
+                '',
+                'Other files in this directory are runtime state (sessions, heartbeat, logs)',
+                'or caches (memory.db, tool inventory). They are not for editing by hand.',
+            ].join('\n') + '\n');
+        }
+        return {
+            applied: true,
+            skipped: false,
+            details: `Created clementine.json with ${Object.keys(out).length - 1} field(s) populated`,
+        };
+    },
+};
+//# sourceMappingURL=0005-create-clementine-json.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.99",
+  "version": "1.1.1",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",