clementine-agent 1.0.45 → 1.0.47

package/dist/agent/assistant.js

@@ -1052,26 +1052,45 @@ Obsidian vault with YAML frontmatter, [[wikilinks]], #tags.
 **Remembering:** Durable facts → memory_write(action="update_memory"). Daily context → note_take / memory_write(action="append_daily"). New person → note_create. New task → task_add.
 Save important facts immediately; a background agent also extracts after each exchange.
 
-## Self-Configuration (don't make the owner edit config files)
+## Self-Configuration (never tell ${owner} to edit a config file)
 
-When ${owner} gives you an API key, access token, or similar credential in chat, **save it yourself** with \`env_set\`. Same for channel tokens, Salesforce creds, OAuth client IDs — anything that would otherwise live in \`.env\`. \`env_set(key, value)\` writes to \`~/.clementine/.env\` and hot-reloads into \`process.env\` so the next tool call can use it. No daemon restart needed for most cases (restart only if a channel adapter needs to re-auth).
+Clementine is self-configuring. Every credential, every integration, every tool permission can be set by calling a tool — no hand-editing.
 
-Use \`env_list\` to show what's configured (values masked) and \`env_unset\` to remove one. All three are owner-DM only — they'll refuse in channel messages or cron runs.
+### Integrations (Slack, Notion, Stripe, Salesforce, etc.)
 
-### When a tool call is refused
+You have a declarative registry of every integration you can configure. Use it:
 
-If any tool call fails with "not in my function schema" / "tool not allowed" / "unknown tool" while you can see the tool exists in your SDK inventory:
+- \`list_integrations\` — shows every integration you know about
+- \`integration_status [slug]\` — reports which are configured, partial (some creds missing), or missing entirely
+- \`setup_integration <slug>\` — returns the required env vars, doc URLs, and current status — use this BEFORE asking ${owner} for any credential
+- \`auth_profile_status\` — shows stored OAuth profiles and token expiry
 
-1. Call \`allow_tool("<exact_tool_name>")\` — persists to your own whitelist
-2. Retry the original call
+**When ${owner} says "set up X":** always call \`setup_integration(x)\` first. It returns the exact env var names and where to get each one. Then walk ${owner} through each missing credential one at a time, saving each with \`env_set\` as they provide it. After the last one, call \`integration_status\` to confirm "configured".
+
+**Never invent env var names.** If an integration isn't in the registry, say so and ask ${owner} to confirm which one they mean — don't guess \`STRIPE_SECRET\` when the registry says \`STRIPE_SECRET_KEY\`.
+
+### Saving credentials
+
+\`env_set(key, value)\` — the one tool for saving any API key, token, or config. On macOS it defaults to the login Keychain (secure); elsewhere it falls back to plaintext \`~/.clementine/.env\`. \`process.env\` is updated immediately — the next tool call can use the value. No restart needed unless a long-lived channel adapter needs re-auth.
 
-Takes effect on your next query. No restart, no config editing, no asking ${owner} to help.
+Companion tools: \`env_list\` (masked values + backend), \`env_unset\` (removes + clears Keychain entry).
 
-**Never** respond with "this tool isn't available to agents" or "you need to edit my config" or "try it in a different app instead." If the tool name appears in your inventory, you can add it. If you genuinely can't find a tool name, ask ${owner} which tool they meant — don't invent rationalizations.
+### Self-update (when ${owner} asks you to update yourself)
 
-\`list_allowed_tools\` shows what you've added. \`disallow_tool\` removes one.
+Call \`self_update\` — **never** manually \`cd ~/clementine && git pull\` or hunt for a source directory. There may be multiple clementine-related directories in home (stale \`~/clementine\`, the real \`~/clementine-dev\`, the data dir \`~/.clementine\`). \`self_update\` knows which source tree this daemon is actually running from — the others are stale or irrelevant and touching them will produce nothing useful while creating dangerous diverging state.
 
-For \`.env\` credentials, same self-service pattern: \`env_set(KEY, value)\` — never tell ${owner} to edit the file.
+If you're unsure what's happening first, run \`where_is_source\` — it reports the absolute source path, current branch/commit, and whether there are uncommitted changes. \`self_update\` does git pull + npm install (if lockfile changed) + npm run build + SIGUSR1 restart, all in the right place.
+
+### When a tool call is refused
+
+If any tool call fails with "not in my function schema" / "tool not allowed" / "unknown tool" while the tool appears in your SDK inventory:
+
+1. Call \`allow_tool("<exact_tool_name>")\` — persists to your whitelist
+2. Retry the original call
+
+Takes effect on your next query. **Never** respond with "this tool isn't available to agents," "you need to edit my config," or "try it in a different app." If the tool name exists, you can add it.
+
+\`list_allowed_tools\` / \`disallow_tool\` manage the list.
 
 ## Context Window Management
 
@@ -1304,6 +1323,18 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         }
         // Security rules are now appended to systemPrompt in buildOptions()
         // Volatile suffix — put last so the stable prefix above stays cache-friendly.
+        // Integration status — injected here (not in the stable prefix) because
+        // it changes as ${owner} configures new credentials, and we don't want
+        // every env_set to invalidate the cache.
+        if (!isAutonomous) {
+            try {
+                const { summarizeIntegrationStatus } = require('../config/integrations-registry.js');
+                const summary = summarizeIntegrationStatus(process.env);
+                if (summary)
+                    parts.push(`## Integration Status\n\n${summary}\n\nCall \`integration_status\`, \`list_integrations\`, or \`setup_integration\` for details.`);
+            }
+            catch { /* non-fatal */ }
+        }
         const channel = deriveChannel({ sessionKey, isAutonomous, cronTier });
         const resolvedModel = resolveModel(model) ?? MODEL;
         const modelLabel = Object.entries(MODELS).find(([, v]) => v === resolvedModel)?.[0] ?? resolvedModel;
@@ -1360,12 +1391,19 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             mcpTool('env_set'),
             mcpTool('env_list'),
             mcpTool('env_unset'),
+            // Integration registry — proactive configuration
+            mcpTool('integration_status'),
+            mcpTool('list_integrations'),
+            mcpTool('setup_integration'),
+            mcpTool('auth_profile_status'),
             // Self-service tool whitelist — Clementine can add tools she discovers
             // in the SDK init inventory but that aren't in her baseline allowedTools
             mcpTool('allow_tool'),
             mcpTool('list_allowed_tools'),
             mcpTool('disallow_tool'),
             mcpTool('self_restart'),
+            mcpTool('self_update'),
+            mcpTool('where_is_source'),
             mcpTool('cron_list'),
             mcpTool('add_cron_job'),
             mcpTool('memory_report'),

package/dist/config/integrations-registry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Clementine TypeScript — Integration registry.
+ *
+ * Declarative metadata for every integration Clementine knows how to set up.
+ * The registry is the single source of truth for:
+ *   - What env vars an integration needs
+ *   - Where to get each credential (doc URLs)
+ *   - Whether the integration is configured right now
+ *   - How to surface gaps to the owner proactively
+ *
+ * Used by:
+ *   - integration_status()  — reports configured/partial/missing per integration
+ *   - setup_integration()   — walks the owner through setup conversationally
+ *   - list_integrations()   — enumerates what's available
+ *   - System prompt         — "Notion is configured, Stripe needs STRIPE_API_KEY"
+ *
+ * Replaces the previous pattern where the agent had to recall from chat
+ * history or invent which env vars a provider needs — the registry tells her
+ * exactly, with docs links, so she never has to guess.
+ */
+export type IntegrationKind = 'api-key' | 'oauth' | 'hybrid' | 'channel';
+export interface IntegrationRequirement {
+    /** Env var name (uppercase, underscores). */
+    envVar: string;
+    /** One-line description shown during setup. */
+    label: string;
+    /** Whether this credential is required (false = optional). */
+    required: boolean;
+    /** Doc link where the owner can find or generate this credential. */
+    docUrl?: string;
+    /** Optional regex the value must match (for early validation). */
+    pattern?: RegExp;
+    /** If true, value is long-lived (API key). If false, short-lived (OAuth token). */
+    persistent?: boolean;
+}
+export interface IntegrationDefinition {
+    /** Machine-readable slug (kebab-case). */
+    slug: string;
+    /** Human-friendly label. */
+    label: string;
+    /** One-line summary shown in status output. */
+    description: string;
+    /** Credential style. */
+    kind: IntegrationKind;
+    /** Required + optional env vars. */
+    requirements: IntegrationRequirement[];
+    /** Top-level docs URL. */
+    docUrl?: string;
+    /** Tools/capabilities this integration unlocks, for the status panel. */
+    capabilities?: string[];
+}
+/**
+ * The curated registry. Keep entries alphabetical within each kind for
+ * easier scanning. Adding a new integration: declare it here, and both
+ * integration_status and setup_integration automatically pick it up.
+ */
+export declare const INTEGRATIONS: IntegrationDefinition[];
+export type IntegrationStatus = 'configured' | 'partial' | 'missing';
+export interface IntegrationStatusReport {
+    slug: string;
+    label: string;
+    status: IntegrationStatus;
+    /** All required env vars that are currently set. */
+    have: string[];
+    /** Required env vars that are missing. */
+    missing: string[];
+    /** Optional env vars that are missing (informational only). */
+    optionalMissing: string[];
+    /** Helpful setup link. */
+    docUrl?: string;
+}
+/**
+ * Classify each integration against the current environment.
+ * Pure function — caller passes in env so this is testable.
+ */
+export declare function classifyIntegrations(env: NodeJS.ProcessEnv, slugs?: string[]): IntegrationStatusReport[];
+export declare function findIntegration(slug: string): IntegrationDefinition | undefined;
+/** A short one-line summary for prompt injection. */
+export declare function summarizeIntegrationStatus(env: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=integrations-registry.d.ts.map

package/dist/config/integrations-registry.js

@@ -0,0 +1,268 @@
+/**
+ * Clementine TypeScript — Integration registry.
+ *
+ * Declarative metadata for every integration Clementine knows how to set up.
+ * The registry is the single source of truth for:
+ *   - What env vars an integration needs
+ *   - Where to get each credential (doc URLs)
+ *   - Whether the integration is configured right now
+ *   - How to surface gaps to the owner proactively
+ *
+ * Used by:
+ *   - integration_status()  — reports configured/partial/missing per integration
+ *   - setup_integration()   — walks the owner through setup conversationally
+ *   - list_integrations()   — enumerates what's available
+ *   - System prompt         — "Notion is configured, Stripe needs STRIPE_API_KEY"
+ *
+ * Replaces the previous pattern where the agent had to recall from chat
+ * history or invent which env vars a provider needs — the registry tells her
+ * exactly, with docs links, so she never has to guess.
+ */
+/**
+ * The curated registry. Keep entries alphabetical within each kind for
+ * easier scanning. Adding a new integration: declare it here, and both
+ * integration_status and setup_integration automatically pick it up.
+ */
+export const INTEGRATIONS = [
+    // NOTE: Anthropic auth is handled through `clementine login` (OAuth) or
+    // the ANTHROPIC_API_KEY env var — it's foundational and managed outside
+    // this registry because the auth path isn't uniform.
+    // ── Channels ──────────────────────────────────────────────────────
+    {
+        slug: 'discord',
+        label: 'Discord',
+        description: 'Main chat channel. Bot token + owner ID required.',
+        kind: 'channel',
+        docUrl: 'https://discord.com/developers/applications',
+        capabilities: ['chat', 'DMs', 'agent bots', 'notifications'],
+        requirements: [
+            { envVar: 'DISCORD_TOKEN', label: 'Bot token', required: true, docUrl: 'https://discord.com/developers/applications', persistent: true },
+            { envVar: 'DISCORD_OWNER_ID', label: 'Your Discord user ID (right-click your name → Copy User ID)', required: true, pattern: /^\d{15,22}$/, persistent: true },
+        ],
+    },
+    {
+        slug: 'slack',
+        label: 'Slack',
+        description: 'Alternate chat channel. Socket-mode app with bot + app tokens.',
+        kind: 'channel',
+        docUrl: 'https://api.slack.com/apps',
+        capabilities: ['chat', 'DMs', 'channel posts'],
+        requirements: [
+            { envVar: 'SLACK_BOT_TOKEN', label: 'Bot token (xoxb-...)', required: true, docUrl: 'https://api.slack.com/apps', pattern: /^xoxb-/, persistent: true },
+            { envVar: 'SLACK_APP_TOKEN', label: 'App-level token (xapp-...)', required: true, docUrl: 'https://api.slack.com/apps', pattern: /^xapp-/, persistent: true },
+            { envVar: 'SLACK_OWNER_USER_ID', label: 'Your Slack user ID (starts with U)', required: false, pattern: /^U[A-Z0-9]{6,}$/, persistent: true },
+        ],
+    },
+    {
+        slug: 'telegram',
+        label: 'Telegram',
+        description: 'Chat channel via Bot API.',
+        kind: 'channel',
+        docUrl: 'https://core.telegram.org/bots',
+        capabilities: ['chat', 'DMs'],
+        requirements: [
+            { envVar: 'TELEGRAM_BOT_TOKEN', label: 'Bot token from @BotFather', required: true, docUrl: 'https://t.me/BotFather', persistent: true },
+            { envVar: 'TELEGRAM_OWNER_CHAT_ID', label: 'Your Telegram chat ID', required: false, pattern: /^-?\d+$/, persistent: true },
+        ],
+    },
+    {
+        slug: 'whatsapp',
+        label: 'WhatsApp (via Twilio)',
+        description: 'Chat channel via Twilio WhatsApp API.',
+        kind: 'channel',
+        docUrl: 'https://www.twilio.com/docs/whatsapp',
+        capabilities: ['chat', 'DMs'],
+        requirements: [
+            { envVar: 'TWILIO_ACCOUNT_SID', label: 'Twilio account SID (AC...)', required: true, pattern: /^AC[a-f0-9]{32}$/i, persistent: true },
+            { envVar: 'TWILIO_AUTH_TOKEN', label: 'Twilio auth token', required: true, persistent: true },
+            { envVar: 'TWILIO_WHATSAPP_FROM', label: 'Twilio WhatsApp sender (whatsapp:+14155238886)', required: true, persistent: true },
+            { envVar: 'WHATSAPP_OWNER_NUMBER', label: 'Your WhatsApp number (E.164 format, e.g. +15551234567)', required: true, pattern: /^\+\d{8,15}$/, persistent: true },
+        ],
+    },
+    // ── Productivity / knowledge ──────────────────────────────────────
+    {
+        slug: 'notion',
+        label: 'Notion',
+        description: 'Read/write Notion pages and databases via integration.',
+        kind: 'api-key',
+        docUrl: 'https://www.notion.so/my-integrations',
+        capabilities: ['docs', 'databases', 'task tracking'],
+        requirements: [
+            { envVar: 'NOTION_API_KEY', label: 'Internal integration secret (secret_... or ntn_...)', required: true, docUrl: 'https://www.notion.so/my-integrations', persistent: true },
+        ],
+    },
+    {
+        slug: 'linear',
+        label: 'Linear',
+        description: 'Issue tracking and project management.',
+        kind: 'api-key',
+        docUrl: 'https://linear.app/settings/api',
+        capabilities: ['issues', 'projects', 'teams'],
+        requirements: [
+            { envVar: 'LINEAR_API_KEY', label: 'Personal API key (lin_api_...)', required: true, docUrl: 'https://linear.app/settings/api', pattern: /^lin_api_/, persistent: true },
+        ],
+    },
+    {
+        slug: 'github',
+        label: 'GitHub',
+        description: 'Read PRs, issues, manage releases.',
+        kind: 'api-key',
+        docUrl: 'https://github.com/settings/tokens',
+        capabilities: ['pull requests', 'issues', 'releases'],
+        requirements: [
+            { envVar: 'GITHUB_TOKEN', label: 'Personal access token (ghp_... or github_pat_...)', required: true, docUrl: 'https://github.com/settings/tokens?type=beta', pattern: /^(ghp_|github_pat_)/, persistent: true },
+        ],
+    },
+    // ── Email / calendar (OAuth) ──────────────────────────────────────
+    {
+        slug: 'microsoft-365',
+        label: 'Microsoft 365 (Outlook/Graph)',
+        description: 'Email, calendar, Teams, SharePoint via Microsoft Graph. OAuth app-only or delegated.',
+        kind: 'oauth',
+        docUrl: 'https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade',
+        capabilities: ['outlook inbox', 'outlook send', 'calendar', 'teams chat'],
+        requirements: [
+            { envVar: 'MS_TENANT_ID', label: 'Azure AD tenant ID', required: true, pattern: /^[a-f0-9-]{36}$/i, persistent: true },
+            { envVar: 'MS_CLIENT_ID', label: 'App registration client ID', required: true, pattern: /^[a-f0-9-]{36}$/i, persistent: true },
+            { envVar: 'MS_CLIENT_SECRET', label: 'App registration client secret value', required: true, persistent: true },
+            { envVar: 'MS_USER_EMAIL', label: 'Your primary email (used for delegated calls)', required: false, pattern: /@/, persistent: true },
+        ],
+    },
+    // ── CRM / sales ───────────────────────────────────────────────────
+    {
+        slug: 'salesforce',
+        label: 'Salesforce',
+        description: 'CRM access via SOAP/REST. Username + password + token flow.',
+        kind: 'api-key',
+        docUrl: 'https://help.salesforce.com/s/articleView?id=sf.code_sample_auth_api_oauth.htm',
+        capabilities: ['leads', 'contacts', 'opportunities', 'custom objects'],
+        requirements: [
+            { envVar: 'SF_INSTANCE_URL', label: 'Salesforce instance URL (https://your-org.my.salesforce.com)', required: true, pattern: /^https?:\/\//, persistent: true },
+            { envVar: 'SF_CLIENT_ID', label: 'Connected app consumer key', required: true, persistent: true },
+            { envVar: 'SF_CLIENT_SECRET', label: 'Connected app consumer secret', required: true, persistent: true },
+            { envVar: 'SF_USERNAME', label: 'Salesforce username (email)', required: true, pattern: /@/, persistent: true },
+            { envVar: 'SF_PASSWORD', label: 'Salesforce password + security token concatenated', required: true, persistent: true },
+        ],
+    },
+    // ── AI auxiliaries ────────────────────────────────────────────────
+    {
+        slug: 'openai',
+        label: 'OpenAI',
+        description: 'GPT + Whisper (used for auxiliary tasks and fallback).',
+        kind: 'api-key',
+        docUrl: 'https://platform.openai.com/api-keys',
+        capabilities: ['transcription', 'image generation', 'fallback model'],
+        requirements: [
+            { envVar: 'OPENAI_API_KEY', label: 'API key (sk-...)', required: true, docUrl: 'https://platform.openai.com/api-keys', pattern: /^sk-/, persistent: true },
+        ],
+    },
+    {
+        slug: 'elevenlabs',
+        label: 'ElevenLabs',
+        description: 'Text-to-speech for voice replies.',
+        kind: 'api-key',
+        docUrl: 'https://elevenlabs.io/app/settings/api-keys',
+        capabilities: ['voice synthesis'],
+        requirements: [
+            { envVar: 'ELEVENLABS_API_KEY', label: 'API key', required: true, docUrl: 'https://elevenlabs.io/app/settings/api-keys', persistent: true },
+        ],
+    },
+    {
+        slug: 'groq',
+        label: 'Groq',
+        description: 'Fast inference, used for real-time transcription.',
+        kind: 'api-key',
+        docUrl: 'https://console.groq.com/keys',
+        capabilities: ['voice transcription'],
+        requirements: [
+            { envVar: 'GROQ_API_KEY', label: 'API key (gsk_...)', required: true, docUrl: 'https://console.groq.com/keys', pattern: /^gsk_/, persistent: true },
+        ],
+    },
+    {
+        slug: 'google-ai',
+        label: 'Google AI (Gemini)',
+        description: 'Used for video analysis and multimodal tasks.',
+        kind: 'api-key',
+        docUrl: 'https://aistudio.google.com/apikey',
+        capabilities: ['video analysis', 'multimodal'],
+        requirements: [
+            { envVar: 'GOOGLE_API_KEY', label: 'Gemini API key', required: true, docUrl: 'https://aistudio.google.com/apikey', persistent: true },
+        ],
+    },
+    // ── Payments ──────────────────────────────────────────────────────
+    {
+        slug: 'stripe',
+        label: 'Stripe',
+        description: 'Payments read/write (one-off or recurring).',
+        kind: 'api-key',
+        docUrl: 'https://dashboard.stripe.com/apikeys',
+        capabilities: ['customers', 'payments', 'subscriptions'],
+        requirements: [
+            { envVar: 'STRIPE_SECRET_KEY', label: 'Secret key (sk_live_... or sk_test_...)', required: true, docUrl: 'https://dashboard.stripe.com/apikeys', pattern: /^sk_(live|test)_/, persistent: true },
+        ],
+    },
+];
+/**
+ * Classify each integration against the current environment.
+ * Pure function — caller passes in env so this is testable.
+ */
+export function classifyIntegrations(env, slugs) {
+    const targets = slugs?.length
+        ? INTEGRATIONS.filter(i => slugs.includes(i.slug))
+        : INTEGRATIONS;
+    return targets.map(integration => {
+        const required = integration.requirements.filter(r => r.required);
+        const optional = integration.requirements.filter(r => !r.required);
+        const have = [];
+        const missing = [];
+        for (const req of required) {
+            if (env[req.envVar])
+                have.push(req.envVar);
+            else
+                missing.push(req.envVar);
+        }
+        const optionalMissing = optional
+            .filter(r => !env[r.envVar])
+            .map(r => r.envVar);
+        let status;
+        if (missing.length === 0 && have.length > 0)
+            status = 'configured';
+        else if (have.length > 0)
+            status = 'partial';
+        else
+            status = 'missing';
+        // Special case for hybrid: "have" counts if ANY required-or-alternative is set.
+        if (integration.kind === 'hybrid' && missing.length > 0 && integration.requirements.some(r => env[r.envVar])) {
+            status = 'configured';
+        }
+        return {
+            slug: integration.slug,
+            label: integration.label,
+            status,
+            have,
+            missing,
+            optionalMissing,
+            docUrl: integration.docUrl,
+        };
+    });
+}
+export function findIntegration(slug) {
+    const normalized = slug.trim().toLowerCase();
+    return INTEGRATIONS.find(i => i.slug === normalized);
+}
+/** A short one-line summary for prompt injection. */
+export function summarizeIntegrationStatus(env) {
+    const reports = classifyIntegrations(env);
+    const configured = reports.filter(r => r.status === 'configured').map(r => r.label);
+    const partial = reports.filter(r => r.status === 'partial').map(r => `${r.label} (missing ${r.missing.join(', ')})`);
+    const missing = reports.filter(r => r.status === 'missing').map(r => r.label);
+    const lines = [];
+    if (configured.length > 0)
+        lines.push(`**Configured:** ${configured.join(', ')}`);
+    if (partial.length > 0)
+        lines.push(`**Partial:** ${partial.join('; ')}`);
+    if (missing.length > 0)
+        lines.push(`**Available but not configured:** ${missing.join(', ')}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=integrations-registry.js.map

package/dist/index.js

@@ -534,6 +534,12 @@ async function asyncMain() {
     for (const warning of secretWarnings) {
         logger.warn(warning);
     }
+    // ── Resolve keychain-backed secrets before anything reads process.env ──
+    try {
+        const { hydrateSecretsFromEnv } = await import('./secrets/resolver.js');
+        hydrateSecretsFromEnv();
+    }
+    catch { /* non-fatal — non-macOS systems, or keychain unavailable */ }
     // ── Check MCP extension permissions ────────────────────────────
     try {
         const { checkPermissionsOnStartup, bootstrapClaudeIntegrationsFromAuditLog, probeAvailableTools } = await import('./agent/mcp-bridge.js');

package/dist/secrets/auth-profiles.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Clementine TypeScript — OAuth auth profile store.
+ *
+ * OAuth tokens (access + refresh + expiry) have different semantics from
+ * API keys: they expire and need refresh. Keeping them in ~/.clementine/.env
+ * alongside long-lived API keys mixes two lifecycles and makes token refresh
+ * awkward. This store keeps them separate at ~/.clementine/auth-profiles/<provider>.json
+ * with mode 0o600, so the OAuth flow code can atomically update tokens
+ * without touching .env.
+ *
+ * Current scope: storage + basic read/write/refresh-check. Callers (outlook,
+ * Google OAuth flows) can adopt this incrementally; existing env-based OAuth
+ * keeps working until migrated.
+ */
+export interface AuthProfile {
+    /** Provider slug (matches integrations-registry, e.g. "microsoft-365"). */
+    provider: string;
+    /** Short-lived access token. */
+    accessToken: string;
+    /** Long-lived refresh token, optional. */
+    refreshToken?: string;
+    /** Unix epoch ms — when accessToken expires. */
+    expiresAt?: number;
+    /** Identifier (email, user id) for the authenticated account. */
+    accountId?: string;
+    /** Comma-delimited scopes granted. */
+    scopes?: string;
+    /** When this profile was first written. */
+    createdAt: string;
+    /** When this profile was last refreshed. */
+    updatedAt: string;
+    /** Provider-specific extras. */
+    extras?: Record<string, unknown>;
+}
+/** Atomic write — write tmp then rename. Mode 0o600. */
+export declare function save(profile: AuthProfile): void;
+export declare function load(provider: string): AuthProfile | null;
+export declare function remove(provider: string): boolean;
+/** List provider slugs with stored profiles. */
+export declare function list(): string[];
+/**
+ * True if accessToken is present and either has no expiry set or expires
+ * more than `bufferMs` from now. Callers should call their refresh flow if
+ * this returns false.
+ */
+export declare function isValid(profile: AuthProfile | null, bufferMs?: number): boolean;
+/** Get access token if valid, else null. Does not refresh — caller refreshes. */
+export declare function getValidAccessToken(provider: string): string | null;
+/** Status summary for status reporting. */
+export interface AuthProfileStatus {
+    provider: string;
+    accountId?: string;
+    valid: boolean;
+    expiresInMinutes: number | null;
+}
+export declare function statusAll(): AuthProfileStatus[];
+//# sourceMappingURL=auth-profiles.d.ts.map

package/dist/secrets/auth-profiles.js

@@ -0,0 +1,111 @@
+/**
+ * Clementine TypeScript — OAuth auth profile store.
+ *
+ * OAuth tokens (access + refresh + expiry) have different semantics from
+ * API keys: they expire and need refresh. Keeping them in ~/.clementine/.env
+ * alongside long-lived API keys mixes two lifecycles and makes token refresh
+ * awkward. This store keeps them separate at ~/.clementine/auth-profiles/<provider>.json
+ * with mode 0o600, so the OAuth flow code can atomically update tokens
+ * without touching .env.
+ *
+ * Current scope: storage + basic read/write/refresh-check. Callers (outlook,
+ * Google OAuth flows) can adopt this incrementally; existing env-based OAuth
+ * keeps working until migrated.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.auth-profiles' });
+const PROFILES_DIR = path.join(BASE_DIR, 'auth-profiles');
+function ensureDir() {
+    if (!existsSync(PROFILES_DIR)) {
+        mkdirSync(PROFILES_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+function profilePath(provider) {
+    const safe = provider.replace(/[^a-z0-9_-]/gi, '_');
+    return path.join(PROFILES_DIR, `${safe}.json`);
+}
+/** Atomic write — write tmp then rename. Mode 0o600. */
+export function save(profile) {
+    ensureDir();
+    const p = profilePath(profile.provider);
+    const tmp = p + '.tmp';
+    const content = JSON.stringify(profile, null, 2);
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, p);
+    logger.info({ provider: profile.provider, account: profile.accountId }, 'Auth profile saved');
+}
+export function load(provider) {
+    const p = profilePath(provider);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function remove(provider) {
+    const p = profilePath(provider);
+    if (!existsSync(p))
+        return false;
+    try {
+        // Overwrite with empty data before unlink so contents aren't trivially recoverable.
+        writeFileSync(p, '');
+        const { unlinkSync } = require('node:fs');
+        unlinkSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List provider slugs with stored profiles. */
+export function list() {
+    ensureDir();
+    try {
+        return readdirSync(PROFILES_DIR)
+            .filter(f => f.endsWith('.json'))
+            .map(f => f.replace(/\.json$/, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * True if accessToken is present and either has no expiry set or expires
+ * more than `bufferMs` from now. Callers should call their refresh flow if
+ * this returns false.
+ */
+export function isValid(profile, bufferMs = 5 * 60 * 1000) {
+    if (!profile?.accessToken)
+        return false;
+    if (!profile.expiresAt)
+        return true;
+    return Date.now() + bufferMs < profile.expiresAt;
+}
+/** Get access token if valid, else null. Does not refresh — caller refreshes. */
+export function getValidAccessToken(provider) {
+    const p = load(provider);
+    return isValid(p) ? p.accessToken : null;
+}
+export function statusAll() {
+    const slugs = list();
+    const now = Date.now();
+    return slugs.map(slug => {
+        const p = load(slug);
+        const valid = isValid(p);
+        const expiresInMinutes = p?.expiresAt ? Math.round((p.expiresAt - now) / 60000) : null;
+        return {
+            provider: slug,
+            accountId: p?.accountId,
+            valid,
+            expiresInMinutes,
+        };
+    });
+}
+//# sourceMappingURL=auth-profiles.js.map

package/dist/secrets/keychain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Clementine TypeScript — macOS Keychain backend for secret storage.
+ *
+ * When available, lets `env_set` store API keys in the user's login keychain
+ * instead of plaintext in ~/.clementine/.env. The .env file then holds only
+ * a reference stub: `STRIPE_API_KEY=keychain:clementine-STRIPE_API_KEY`.
+ *
+ * Graceful fallback: on non-macOS systems or when `security` is unavailable,
+ * isAvailable() returns false and callers fall back to raw .env storage.
+ *
+ * Secrets are stored under service "clementine-agent" with the env var
+ * name as the account label, so the user can inspect / revoke them via
+ * Keychain Access.app if needed.
+ */
+/** Is macOS keychain usable in this environment? */
+export declare function isAvailable(): boolean;
+/**
+ * Construct the stub value written to .env when a secret is keychain-backed.
+ * Reading this back through resolver.ts triggers a keychain lookup.
+ */
+export declare function makeRef(envVar: string): string;
+export declare function isRef(value: string): boolean;
+/** Parse a ref stub back into its account name, or null if not a ref. */
+export declare function parseRef(value: string): {
+    account: string;
+} | null;
+/** Write a secret. Returns the ref stub suitable for .env. */
+export declare function set(envVar: string, value: string): string;
+/** Read a secret back. Returns undefined if missing or unreadable. */
+export declare function get(envVar: string): string | undefined;
+/** Delete a secret. No-op if it doesn't exist. */
+export declare function remove(envVar: string): boolean;
+/** List env var names that have keychain entries (best-effort). */
+export declare function list(): string[];
+//# sourceMappingURL=keychain.d.ts.map

package/dist/secrets/keychain.js

@@ -0,0 +1,119 @@
+/**
+ * Clementine TypeScript — macOS Keychain backend for secret storage.
+ *
+ * When available, lets `env_set` store API keys in the user's login keychain
+ * instead of plaintext in ~/.clementine/.env. The .env file then holds only
+ * a reference stub: `STRIPE_API_KEY=keychain:clementine-STRIPE_API_KEY`.
+ *
+ * Graceful fallback: on non-macOS systems or when `security` is unavailable,
+ * isAvailable() returns false and callers fall back to raw .env storage.
+ *
+ * Secrets are stored under service "clementine-agent" with the env var
+ * name as the account label, so the user can inspect / revoke them via
+ * Keychain Access.app if needed.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.keychain' });
+const SERVICE_NAME = 'clementine-agent';
+const REF_PREFIX = 'keychain:'; // pragma: allowlist secret
+/** Is macOS keychain usable in this environment? */
+export function isAvailable() {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        execFileSync('/usr/bin/security', ['-h'], {
+            stdio: 'pipe',
+            timeout: 1000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Construct the stub value written to .env when a secret is keychain-backed.
+ * Reading this back through resolver.ts triggers a keychain lookup.
+ */
+export function makeRef(envVar) {
+    return `${REF_PREFIX}${SERVICE_NAME}-${envVar}`;
+}
+export function isRef(value) {
+    return value.startsWith(REF_PREFIX);
+}
+/** Parse a ref stub back into its account name, or null if not a ref. */
+export function parseRef(value) {
+    if (!isRef(value))
+        return null;
+    return { account: value.slice(REF_PREFIX.length) };
+}
+/** Write a secret. Returns the ref stub suitable for .env. */
+export function set(envVar, value) {
+    if (!isAvailable()) {
+        throw new Error('Keychain unavailable on this platform');
+    }
+    const account = `${SERVICE_NAME}-${envVar}`;
+    // -U updates existing entry in place; -s = service; -a = account; -w = password
+    const result = spawnSync('/usr/bin/security', [
+        'add-generic-password',
+        '-U',
+        '-s', SERVICE_NAME,
+        '-a', account,
+        '-w', value,
+        '-T', '', // no apps pre-approved — will prompt on first read; user can approve for login session
+        '-l', `Clementine: ${envVar}`,
+    ], { stdio: 'pipe' });
+    if (result.status !== 0) {
+        throw new Error(`security add-generic-password failed (code ${result.status}): ${result.stderr.toString().slice(0, 200)}`);
+    }
+    return makeRef(envVar);
+}
+/** Read a secret back. Returns undefined if missing or unreadable. */
+export function get(envVar) {
+    if (!isAvailable())
+        return undefined;
+    const account = `${SERVICE_NAME}-${envVar}`;
+    const result = spawnSync('/usr/bin/security', [
+        'find-generic-password',
+        '-s', SERVICE_NAME,
+        '-a', account,
+        '-w',
+    ], { stdio: 'pipe' });
+    if (result.status !== 0) {
+        // Exit code 44 = item not found — expected, don't log
+        if (result.status !== 44) {
+            logger.debug({ code: result.status, envVar }, 'keychain read non-zero');
+        }
+        return undefined;
+    }
+    const value = result.stdout.toString();
+    // security prints a trailing newline we need to strip
+    return value.replace(/\r?\n$/, '');
+}
+/** Delete a secret. No-op if it doesn't exist. */
+export function remove(envVar) {
+    if (!isAvailable())
+        return false;
+    const account = `${SERVICE_NAME}-${envVar}`;
+    const result = spawnSync('/usr/bin/security', [
+        'delete-generic-password',
+        '-s', SERVICE_NAME,
+        '-a', account,
+    ], { stdio: 'pipe' });
+    return result.status === 0;
+}
+/** List env var names that have keychain entries (best-effort). */
+export function list() {
+    if (!isAvailable())
+        return [];
+    const result = spawnSync('/usr/bin/security', [
+        'dump-keychain',
+    ], { stdio: 'pipe', timeout: 5000 });
+    if (result.status !== 0)
+        return [];
+    const out = result.stdout.toString();
+    const matches = out.matchAll(new RegExp(`"acct"<blob>="${SERVICE_NAME}-([^"]+)"`, 'g'));
+    return [...new Set([...matches].map(m => m[1]))];
+}
+//# sourceMappingURL=keychain.js.map

package/dist/secrets/resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Clementine TypeScript — Secret reference resolver.
+ *
+ * When code reads process.env.FOO, it should get the resolved SECRET VALUE
+ * regardless of whether that secret is stored plaintext in .env or as a
+ * keychain ref stub (`keychain:clementine-agent-FOO`). This module bridges
+ * the gap: called once at daemon boot, it walks process.env, detects ref
+ * stubs, resolves them via the appropriate backend, and replaces the stub
+ * with the real value in-place.
+ *
+ * After hydrate(), downstream code can treat process.env as usual — it has
+ * no knowledge of keychain/1Password/etc. This mirrors OpenClaw's SecretRef
+ * pattern but narrower: one backend (macOS Keychain), one convention.
+ */
+/**
+ * Check every env var for a ref stub and resolve in place. Returns a summary
+ * of what was resolved / failed so startup can log visibility.
+ */
+export declare function hydrateSecretsFromEnv(): {
+    resolved: string[];
+    failed: string[];
+};
+/**
+ * Lazy single-key lookup — reads process.env[key], resolves the ref if
+ * needed, returns the resolved value. Useful when code calls us at runtime
+ * rather than relying on startup hydration.
+ */
+export declare function resolveEnvValue(key: string): string | undefined;
+/**
+ * Classify a given value by its storage backend (for status reporting).
+ * Returns e.g. "keychain" or "env" or undefined (not set).
+ */
+export declare function secretBackend(envVar: string): 'keychain' | 'env' | undefined;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/secrets/resolver.js

@@ -0,0 +1,70 @@
+/**
+ * Clementine TypeScript — Secret reference resolver.
+ *
+ * When code reads process.env.FOO, it should get the resolved SECRET VALUE
+ * regardless of whether that secret is stored plaintext in .env or as a
+ * keychain ref stub (`keychain:clementine-agent-FOO`). This module bridges
+ * the gap: called once at daemon boot, it walks process.env, detects ref
+ * stubs, resolves them via the appropriate backend, and replaces the stub
+ * with the real value in-place.
+ *
+ * After hydrate(), downstream code can treat process.env as usual — it has
+ * no knowledge of keychain/1Password/etc. This mirrors OpenClaw's SecretRef
+ * pattern but narrower: one backend (macOS Keychain), one convention.
+ */
+import pino from 'pino';
+import * as keychain from './keychain.js';
+const logger = pino({ name: 'clementine.secrets' });
+/**
+ * Check every env var for a ref stub and resolve in place. Returns a summary
+ * of what was resolved / failed so startup can log visibility.
+ */
+export function hydrateSecretsFromEnv() {
+    const resolved = [];
+    const failed = [];
+    for (const [key, rawValue] of Object.entries(process.env)) {
+        if (!rawValue)
+            continue;
+        if (!keychain.isRef(rawValue))
+            continue;
+        const resolvedValue = keychain.get(key);
+        if (resolvedValue !== undefined) {
+            process.env[key] = resolvedValue;
+            resolved.push(key);
+        }
+        else {
+            failed.push(key);
+            // Leave the ref stub in place so downstream errors are obvious rather
+            // than silently returning the literal "keychain:..." as if it were a
+            // real API key.
+        }
+    }
+    if (resolved.length > 0 || failed.length > 0) {
+        logger.info({ resolved: resolved.length, failed }, 'Secrets hydrated');
+    }
+    return { resolved, failed };
+}
+/**
+ * Lazy single-key lookup — reads process.env[key], resolves the ref if
+ * needed, returns the resolved value. Useful when code calls us at runtime
+ * rather than relying on startup hydration.
+ */
+export function resolveEnvValue(key) {
+    const raw = process.env[key];
+    if (!raw)
+        return undefined;
+    if (!keychain.isRef(raw))
+        return raw;
+    return keychain.get(key);
+}
+/**
+ * Classify a given value by its storage backend (for status reporting).
+ * Returns e.g. "keychain" or "env" or undefined (not set).
+ */
+export function secretBackend(envVar) {
+    const raw = process.env[envVar];
+    if (!raw)
+        return undefined;
+    return keychain.isRef(raw) ? 'keychain' : 'env';
+}
+//# sourceMappingURL=resolver.js.map

package/dist/tools/admin-tools.js

@@ -17,6 +17,9 @@ import { z } from 'zod';
 import { BASE_DIR, CRON_FILE, SYSTEM_DIR, env, getStore, logger, textResult, } from './shared.js';
 import { getInteractionSource } from '../agent/hooks.js';
 import { renameSync } from 'node:fs';
+import * as keychain from '../secrets/keychain.js';
+import * as authProfiles from '../secrets/auth-profiles.js';
+import { classifyIntegrations, findIntegration, INTEGRATIONS } from '../config/integrations-registry.js';
 function readEnvFile() { return env; }
 // ── Env file management helpers (tools registered inside registerAdminTools) ──
 const ENV_PATH = path.join(BASE_DIR, '.env');
@@ -113,10 +116,11 @@ export function registerAdminTools(server) {
         return textResult(`Timer set. Reminder in ${minutes} minute${minutes !== 1 ? 's' : ''} (~${fireTime}): "${message}"`);
     });
     // ── Env self-configuration (owner-DM only) ────────────────────────────
-    server.tool('env_set', 'Save or update an environment variable in ~/.clementine/.env (API keys, tokens, config). Owner-DM only. Changes take effect immediately — the new value becomes available to process.env and to the next tool call. Use this when the owner gives a credential in chat instead of telling them to hand-edit files.', {
+    server.tool('env_set', 'Save or update a credential (API key, token, config). Owner-DM only. On macOS it defaults to the login Keychain for security — the .env file only gets a reference stub. Changes take effect immediately; process.env gets the real value and the next tool call can use it. Use this when the owner gives a credential in chat — never tell them to hand-edit files.', {
         key: z.string().describe('Env var name (uppercase with underscores, e.g. STRIPE_API_KEY)'),
         value: z.string().describe('The value to store. Never echo back to the user; it will be masked in logs.'),
-    }, async ({ key, value }) => {
+        storage: z.enum(['keychain', 'env', 'auto']).optional().describe('Where to store it. "auto" (default) uses macOS Keychain when available, falls back to plain .env. "keychain" forces Keychain. "env" forces plaintext .env.'),
+    }, async ({ key, value, storage }) => {
         const gate = requireOwnerDm();
         if (!gate.ok)
             return textResult(gate.message);
@@ -126,18 +130,41 @@ export function registerAdminTools(server) {
         }
         if (!value)
             return textResult('Refused: empty value. Use env_unset to remove a key.');
+        const mode = storage ?? 'auto';
+        const useKeychain = (mode === 'keychain') || (mode === 'auto' && keychain.isAvailable());
+        if (mode === 'keychain' && !keychain.isAvailable()) {
+            return textResult('Refused: Keychain storage requested but macOS Keychain is unavailable on this system.');
+        }
         const map = parseEnvFile();
         const existed = map.has(normalizedKey);
-        map.set(normalizedKey, value);
+        let envFileValue;
+        let backendNote;
+        if (useKeychain) {
+            try {
+                envFileValue = keychain.set(normalizedKey, value);
+                backendNote = 'stored in macOS Keychain (service: clementine-agent); .env holds only a reference';
+            }
+            catch (err) {
+                logger.warn({ err, key: normalizedKey }, 'Keychain write failed — falling back to plain .env');
+                envFileValue = value;
+                backendNote = `Keychain unavailable (${String(err).slice(0, 100)}) — stored plaintext in .env`;
+            }
+        }
+        else {
+            envFileValue = value;
+            backendNote = 'stored plaintext in .env';
+        }
+        map.set(normalizedKey, envFileValue);
         try {
             writeEnvFile(map);
         }
         catch (err) {
             return textResult(`Failed to write .env: ${String(err).slice(0, 200)}`);
         }
+        // process.env gets the REAL value regardless of backend, so tools can use it now
         process.env[normalizedKey] = value;
-        logger.info({ key: normalizedKey, existed, masked: maskSecret(value) }, 'env_set');
-        return textResult(`${existed ? 'Updated' : 'Added'} ${normalizedKey} in ~/.clementine/.env (value: ${maskSecret(value)}). Available to tools immediately; a daemon restart is not required for most cases.`);
+        logger.info({ key: normalizedKey, existed, masked: maskSecret(value), storage: useKeychain ? 'keychain' : 'env' }, 'env_set');
+        return textResult(`${existed ? 'Updated' : 'Added'} ${normalizedKey} (value: ${maskSecret(value)}). ${backendNote}. Active immediately — no restart needed.`);
     });
     server.tool('env_list', 'List the names of environment variables configured in ~/.clementine/.env. Returns key names only — values are masked. Owner-DM only.', {}, async () => {
         const gate = requireOwnerDm();
@@ -149,7 +176,7 @@ export function registerAdminTools(server) {
         const lines = [...map.entries()].map(([k, v]) => `- ${k} = ${maskSecret(v)}`);
         return textResult(`Configured env vars (${map.size}):\n${lines.join('\n')}`);
     });
-    server.tool('env_unset', 'Remove an environment variable from ~/.clementine/.env. Owner-DM only. Also clears from the running process.', {
+    server.tool('env_unset', 'Remove an environment variable. Owner-DM only. Also clears from Keychain (if backed by Keychain) and from the running process.', {
         key: z.string().describe('Env var name to remove'),
     }, async ({ key }) => {
         const gate = requireOwnerDm();
@@ -157,6 +184,7 @@ export function registerAdminTools(server) {
             return textResult(gate.message);
         const normalizedKey = key.trim();
         const map = parseEnvFile();
+        const hadKeychain = map.has(normalizedKey) && keychain.isRef(map.get(normalizedKey) ?? '');
         if (!map.has(normalizedKey))
             return textResult(`${normalizedKey} is not set in ~/.clementine/.env`);
         map.delete(normalizedKey);
@@ -166,9 +194,104 @@ export function registerAdminTools(server) {
         catch (err) {
             return textResult(`Failed to write .env: ${String(err).slice(0, 200)}`);
         }
+        if (hadKeychain) {
+            try {
+                keychain.remove(normalizedKey);
+            }
+            catch { /* best-effort */ }
+        }
         delete process.env[normalizedKey];
-        logger.info({ key: normalizedKey }, 'env_unset');
-        return textResult(`Removed ${normalizedKey} from ~/.clementine/.env`);
+        logger.info({ key: normalizedKey, keychainCleared: hadKeychain }, 'env_unset');
+        return textResult(`Removed ${normalizedKey}${hadKeychain ? ' (including Keychain entry)' : ''}.`);
+    });
+    server.tool('env_list', 'List configured env vars with their storage backend (Keychain or plaintext) and masked values. Owner-DM only.', {}, async () => {
+        const gate = requireOwnerDm();
+        if (!gate.ok)
+            return textResult(gate.message);
+        const map = parseEnvFile();
+        if (map.size === 0)
+            return textResult('No env vars configured.');
+        const lines = [...map.entries()].map(([k, v]) => {
+            const backend = keychain.isRef(v) ? '[keychain]' : '[env]    ';
+            const resolved = keychain.isRef(v) ? (keychain.get(k) ?? '(keychain read failed)') : v;
+            return `${backend} ${k} = ${maskSecret(resolved)}`;
+        });
+        return textResult(`Configured env vars (${map.size}):\n${lines.join('\n')}`);
+    });
+    // ── Integration registry tools ──────────────────────────────────────
+    server.tool('integration_status', 'Show which third-party integrations (Slack, Notion, Stripe, etc.) are configured, partial (some credentials set, others missing), or missing entirely. Use this when the owner asks "what\'s set up?" or when you need to know whether to expect a credential before attempting a tool call. Reports the declarative registry — do not invent integrations not listed here.', {
+        slug: z.string().optional().describe('Optional: specific integration slug to check (e.g. "slack"). If omitted, returns all.'),
+    }, async ({ slug }) => {
+        const slugs = slug ? [slug] : undefined;
+        const reports = classifyIntegrations(process.env, slugs);
+        if (reports.length === 0)
+            return textResult(`Unknown integration slug: ${slug}. Use list_integrations to see available.`);
+        const icon = (s) => s === 'configured' ? '✓' : s === 'partial' ? '~' : '✗';
+        const lines = reports.map(r => {
+            const base = `${icon(r.status)} ${r.label} (${r.slug}) — ${r.status}`;
+            const detail = [];
+            if (r.have.length > 0)
+                detail.push(`have: ${r.have.join(', ')}`);
+            if (r.missing.length > 0)
+                detail.push(`missing: ${r.missing.join(', ')}`);
+            if (r.optionalMissing.length > 0)
+                detail.push(`optional not set: ${r.optionalMissing.join(', ')}`);
+            return detail.length > 0 ? `${base}\n    ${detail.join(' | ')}` : base;
+        });
+        return textResult(lines.join('\n'));
+    });
+    server.tool('list_integrations', 'List every integration Clementine knows how to configure, with one-line descriptions. Use this to answer "what can I hook up?" or to find the slug for setup_integration.', {}, async () => {
+        const lines = INTEGRATIONS.map(i => {
+            const required = i.requirements.filter(r => r.required).map(r => r.envVar).join(', ');
+            return `- **${i.label}** (\`${i.slug}\`, ${i.kind}): ${i.description}${required ? ` — requires ${required}` : ''}`;
+        });
+        return textResult(`Available integrations (${INTEGRATIONS.length}):\n${lines.join('\n')}`);
+    });
+    server.tool('setup_integration', 'Get the step-by-step setup info for an integration: required env vars, doc URLs for where to find each credential, and current status. Use this when the owner says "set up Slack" or similar — call this first, then walk them through each missing credential conversationally and save each one with env_set. Never guess at required env vars; trust this registry.', {
+        slug: z.string().describe('Integration slug from list_integrations (e.g. "slack", "notion", "stripe")'),
+    }, async ({ slug }) => {
+        const integration = findIntegration(slug);
+        if (!integration) {
+            return textResult(`Unknown integration slug: ${slug}. Run list_integrations to see what's available.`);
+        }
+        const [status] = classifyIntegrations(process.env, [integration.slug]);
+        const lines = [];
+        lines.push(`## ${integration.label} (${integration.slug})`);
+        lines.push('');
+        lines.push(integration.description);
+        if (integration.docUrl)
+            lines.push(`Docs: ${integration.docUrl}`);
+        if (integration.capabilities?.length)
+            lines.push(`Unlocks: ${integration.capabilities.join(', ')}`);
+        lines.push('');
+        lines.push(`**Current status:** ${status.status}${status.have.length ? ` (have ${status.have.join(', ')})` : ''}`);
+        lines.push('');
+        lines.push('**Credentials:**');
+        for (const req of integration.requirements) {
+            const present = !!process.env[req.envVar];
+            const badge = present ? '✓ set' : (req.required ? '✗ REQUIRED' : '○ optional');
+            const line = `- \`${req.envVar}\` — ${req.label} [${badge}]`;
+            lines.push(line);
+            if (!present && req.docUrl)
+                lines.push(`  → ${req.docUrl}`);
+        }
+        lines.push('');
+        lines.push('Next step: ask the owner for each unset REQUIRED credential, one at a time, and save each with env_set. Quote the doc URL when you ask so they know where to find it. After saving the last one, run integration_status to confirm "configured".');
+        return textResult(lines.join('\n'));
+    });
+    // ── OAuth profile tools ────────────────────────────────────────────
+    server.tool('auth_profile_status', 'Show stored OAuth profiles (for providers that use OAuth, not just API keys). Reports which accounts are authenticated and when tokens expire. Owner-DM only.', {}, async () => {
+        const gate = requireOwnerDm();
+        if (!gate.ok)
+            return textResult(gate.message);
+        const statuses = authProfiles.statusAll();
+        if (statuses.length === 0)
+            return textResult('No OAuth profiles stored. (API-key integrations are tracked via integration_status instead.)');
+        const lines = statuses.map(s => {
+            const exp = s.expiresInMinutes === null ? 'no expiry' : s.expiresInMinutes < 0 ? `expired ${Math.abs(s.expiresInMinutes)}m ago` : `expires in ${s.expiresInMinutes}m`;
+            return `- ${s.provider}${s.accountId ? ` (${s.accountId})` : ''}: ${s.valid ? '✓' : '✗'} ${exp}`;
+        });
+        return textResult(`OAuth profiles:\n${lines.join('\n')}`);
     });
     // ── Self-service tool whitelist ────────────────────────────────────────
     const ALLOWED_TOOLS_EXTRA = path.join(BASE_DIR, 'allowed-tools-extra.json');
@@ -1258,8 +1381,128 @@ export function registerAdminTools(server) {
                 (args_description ? `Args: ${args_description}` : ''));
         }
     });
-    // ── Self-Restart ────────────────────────────────────────────────────────
-    server.tool('self_restart', 'Restart the Clementine daemon to pick up code changes. Sends SIGUSR1 to the running process, which triggers a graceful restart.', { _empty: z.string().optional().describe('(no parameters needed)') }, async () => {
+    // ── Self-Update / Self-Restart ─────────────────────────────────────────
+    /** Resolve the git-clone source dir this daemon is running from. */
+    function resolvePackageRoot() {
+        // This file is at clementine-dev/dist/tools/admin-tools.js at runtime.
+        // Climb two dirs to get the package root.
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        return path.resolve(here, '..', '..');
+    }
+    server.tool('where_is_source', 'Report the absolute path of the source tree this daemon is running from, whether it\'s a git clone, the current commit, and whether it has local uncommitted changes. Call this first before any self_update to confirm which checkout you\'re about to modify — avoids the "multiple clones in home dir" confusion where an agent updates the wrong one.', {}, async () => {
+        const root = resolvePackageRoot();
+        const gitDir = path.join(root, '.git');
+        const isGit = existsSync(gitDir);
+        const lines = [`Package root: ${root}`, `Git repo: ${isGit ? 'yes' : 'no'}`];
+        if (isGit) {
+            try {
+                const commit = execSync('git rev-parse --short HEAD', { cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                lines.push(`Branch: ${branch} @ ${commit}`);
+                lines.push(`Uncommitted changes: ${status ? 'yes' : 'no'}`);
+                if (status)
+                    lines.push(`\n${status}`);
+            }
+            catch { /* best-effort */ }
+        }
+        lines.push('', 'ONLY modify files under this path when updating source. Other ~/clementine* directories may be stale checkouts — ignore them.');
+        return textResult(lines.join('\n'));
+    });
+    server.tool('self_update', 'Update Clementine to the latest main-branch code and restart. Runs git pull + npm install (if lockfile changed) + npm run build in the running daemon\'s source dir, then signals SIGUSR1 to restart. Owner-DM only. Use this instead of manually invoking git/npm — it operates on the correct source dir and handles the restart cleanly. Returns immediately; the daemon will be unreachable for ~15s during rebuild+restart.', {
+        branch: z.string().optional().describe('Branch to pull (default "main")'),
+    }, async ({ branch }) => {
+        const gate = requireOwnerDm();
+        if (!gate.ok)
+            return textResult(gate.message);
+        const root = resolvePackageRoot();
+        if (!existsSync(path.join(root, '.git'))) {
+            return textResult(`Refused: ${root} is not a git clone. This daemon was likely installed via npm — updates should go through \`npm install -g clementine-agent@latest\`, not self_update.`);
+        }
+        const targetBranch = branch ?? 'main';
+        const out = [];
+        const runQuiet = (cmd, args, timeout = 120000) => {
+            try {
+                const res = execSync(`${cmd} ${args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, {
+                    cwd: root, encoding: 'utf-8', timeout,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                return { ok: true, output: res };
+            }
+            catch (e) {
+                return { ok: false, output: (e?.stdout ?? '') + '\n' + (e?.stderr ?? '') + '\n' + String(e).slice(0, 200) };
+            }
+        };
+        // 1. Stash local changes so git pull is clean
+        const statusProbe = runQuiet('git', ['status', '--porcelain']);
+        const hadLocal = statusProbe.ok && statusProbe.output.trim().length > 0;
+        let stashed = false;
+        if (hadLocal) {
+            const stashRes = runQuiet('git', ['stash', 'push', '-u', '-m', `self_update ${new Date().toISOString()}`]);
+            if (stashRes.ok) {
+                stashed = true;
+                out.push('Stashed local changes (restore with `git stash pop` in the source dir if needed).');
+            }
+            else {
+                return textResult(`Refused: couldn't stash local changes in ${root}. ${stashRes.output.slice(0, 200)}`);
+            }
+        }
+        // 2. Checkout target branch if not already there
+        const branchProbe = runQuiet('git', ['rev-parse', '--abbrev-ref', 'HEAD']);
+        if (branchProbe.ok && branchProbe.output.trim() !== targetBranch) {
+            const coRes = runQuiet('git', ['checkout', targetBranch]);
+            if (!coRes.ok)
+                return textResult(`git checkout ${targetBranch} failed: ${coRes.output.slice(0, 300)}`);
+        }
+        // 3. Record pre-pull hashes so we know if package-lock changed
+        const preLock = existsSync(path.join(root, 'package-lock.json')) ? readFileSync(path.join(root, 'package-lock.json'), 'utf-8').length : 0;
+        const preCommit = runQuiet('git', ['rev-parse', 'HEAD']).output.trim();
+        // 4. Pull
+        const pullRes = runQuiet('git', ['pull', '--ff-only', 'origin', targetBranch], 60000);
+        if (!pullRes.ok)
+            return textResult(`git pull failed: ${pullRes.output.slice(0, 300)}\n\n${stashed ? 'Local changes are preserved in git stash; inspect with `git stash list`.' : ''}`);
+        const postCommit = runQuiet('git', ['rev-parse', 'HEAD']).output.trim();
+        if (preCommit === postCommit) {
+            out.push(`Already up to date at ${preCommit.slice(0, 7)}.`);
+            return textResult(out.join('\n'));
+        }
+        out.push(`Pulled: ${preCommit.slice(0, 7)} → ${postCommit.slice(0, 7)}`);
+        // 5. npm install only if package-lock changed
+        const postLock = existsSync(path.join(root, 'package-lock.json')) ? readFileSync(path.join(root, 'package-lock.json'), 'utf-8').length : 0;
+        if (postLock !== preLock) {
+            out.push('package-lock.json changed — running npm install...');
+            const installRes = runQuiet('npm', ['install'], 180000);
+            if (!installRes.ok)
+                return textResult(`${out.join('\n')}\n\nnpm install failed: ${installRes.output.slice(0, 300)}`);
+            out.push('  ok');
+        }
+        // 6. Build
+        out.push('Building...');
+        const buildRes = runQuiet('npm', ['run', 'build'], 300000);
+        if (!buildRes.ok)
+            return textResult(`${out.join('\n')}\n\nBuild failed: ${buildRes.output.slice(0, 300)}`);
+        out.push('  ok');
+        // 7. Trigger graceful self-restart
+        const pidFile = path.join(BASE_DIR, `.${(env['ASSISTANT_NAME'] ?? 'clementine').toLowerCase()}.pid`);
+        if (existsSync(pidFile)) {
+            const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+            if (!isNaN(pid)) {
+                try {
+                    process.kill(pid, 0);
+                    process.kill(pid, 'SIGUSR1');
+                    out.push(`Sent SIGUSR1 to PID ${pid}. I'll be back in ~15s on the new build.`);
+                }
+                catch {
+                    out.push('Daemon PID not running — no restart signal sent. New build is on disk; launch manually.');
+                }
+            }
+        }
+        else {
+            out.push('No PID file found. Build succeeded but restart not triggered — run `clementine launch` manually.');
+        }
+        return textResult(out.join('\n'));
+    });
+    server.tool('self_restart', 'Restart the Clementine daemon to pick up code changes. Sends SIGUSR1 to the running process, which triggers a graceful restart. Use self_update instead if you also need to pull/build first.', { _empty: z.string().optional().describe('(no parameters needed)') }, async () => {
         const pidFile = path.join(BASE_DIR, `.${(env['ASSISTANT_NAME'] ?? 'clementine').toLowerCase()}.pid`);
         if (!existsSync(pidFile)) {
             return textResult('No PID file found — daemon may not be running.');

package/package.json

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