@bbigbang/core 0.1.0

package/dist/services/suggestedPlannerService.js

@@ -0,0 +1,868 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPlatformAgentConversationTitle, getPlatformAgentDisabledToolKinds, getPlatformAgentLegacyConversationTitles, } from './platformAgentPolicy.js';
+import { insertPlannerTaskCandidateOpportunity } from '../web/proactiveOpportunities.js';
+export const SUGGESTED_PLANNER_AGENT_NAME = 'Suggested Planner';
+export const DEFAULT_SUGGESTED_PLANNER_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_LOOKBACK_DAYS = 14;
+const PLANNER_WORKSPACE_DIRECTORY_NAME = '.suggested-planner';
+const PLANNER_DISABLED_TOOL_KINDS_JSON = JSON.stringify(getPlatformAgentDisabledToolKinds('suggested_planner'));
+function mapConfigRow(row) {
+    return {
+        userId: row.userId,
+        plannerAgentId: row.plannerAgentId,
+        nodeId: row.nodeId,
+        scheduleIntervalMs: row.scheduleIntervalMs,
+        lookbackDays: row.lookbackDays,
+        lastRunAt: row.lastRunAt,
+        nextRunAt: row.nextRunAt,
+        enabled: row.enabled === 1,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+function safeUsername(username) {
+    return username.replace(/[^a-zA-Z0-9._-]+/g, '_').trim() || 'user';
+}
+function buildPlannerWorkspacePath(workspaceRoot, username) {
+    return path.join(workspaceRoot, PLANNER_WORKSPACE_DIRECTORY_NAME, safeUsername(username));
+}
+function buildPlannerEnvVars() {
+    const envVars = {};
+    const baseUrl = process.env.SUGGESTED_PLANNER_ANTHROPIC_BASE_URL?.trim()
+        || process.env.ANTHROPIC_BASE_URL?.trim();
+    const model = process.env.SUGGESTED_PLANNER_ANTHROPIC_MODEL?.trim()
+        || process.env.ANTHROPIC_MODEL?.trim()
+        || 'deepseek-v4-pro';
+    const authToken = process.env.SUGGESTED_PLANNER_ANTHROPIC_AUTH_TOKEN?.trim()
+        || process.env.SUGGESTED_PLANNER_ANTHROPIC_API_KEY?.trim()
+        || process.env.ANTHROPIC_AUTH_TOKEN?.trim()
+        || process.env.ANTHROPIC_API_KEY?.trim();
+    if (baseUrl)
+        envVars.ANTHROPIC_BASE_URL = baseUrl;
+    if (model)
+        envVars.ANTHROPIC_MODEL = model;
+    if (authToken)
+        envVars.ANTHROPIC_AUTH_TOKEN = authToken;
+    for (const key of [
+        'ANTHROPIC_DEFAULT_OPUS_MODEL',
+        'ANTHROPIC_DEFAULT_SONNET_MODEL',
+        'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+        'CLAUDE_CODE_SUBAGENT_MODEL',
+        'CLAUDE_CODE_EFFORT_LEVEL',
+    ]) {
+        const value = process.env[key]?.trim();
+        if (value)
+            envVars[key] = value;
+    }
+    return envVars;
+}
+function pickPlannerNodeId(nodeRegistry) {
+    const localNode = nodeRegistry.getNode('local-node-1');
+    if (localNode?.agentTypes.includes('claude_sdk'))
+        return localNode.nodeId;
+    for (const node of nodeRegistry.listNodes()) {
+        const agentTypes = Array.isArray(node.agentTypes) ? node.agentTypes : [];
+        if (agentTypes.includes('claude_sdk') && !node.nodeId.startsWith('scenario-'))
+            return node.nodeId;
+    }
+    for (const node of nodeRegistry.listNodes()) {
+        const agentTypes = Array.isArray(node.agentTypes) ? node.agentTypes : [];
+        if (agentTypes.includes('claude_sdk'))
+            return node.nodeId;
+    }
+    return nodeRegistry.listNodes()[0]?.nodeId ?? null;
+}
+function normalizeText(value, limit = 500) {
+    return String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, limit);
+}
+function parseJsonObject(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseJsonRecord(raw) {
+    if (!raw?.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+        if (fenced && fenced !== raw)
+            return parseJsonRecord(fenced);
+        const start = raw.indexOf('{');
+        const end = raw.lastIndexOf('}');
+        if (start >= 0 && end > start)
+            return parseJsonRecord(raw.slice(start, end + 1));
+        return null;
+    }
+}
+function normalizePlannerString(value, limit) {
+    return normalizeText(value, limit);
+}
+function normalizePriority(value) {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    if (normalized === 'high' || normalized === 'medium' || normalized === 'low')
+        return normalized;
+    return 'medium';
+}
+function isSafeEvidenceUrl(url) {
+    if (url.startsWith('/') && !url.startsWith('//'))
+        return true;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeEvidenceLinks(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.slice(0, 4)
+        .map((item) => {
+        if (!item || typeof item !== 'object')
+            return null;
+        const record = item;
+        const label = normalizePlannerString(record.label, 100);
+        const url = normalizePlannerString(record.url, 1000);
+        const summary = normalizePlannerString(record.summary, 240);
+        if (!label || !url)
+            return null;
+        if (!isSafeEvidenceUrl(url))
+            return null;
+        return { label, url, ...(summary ? { summary } : {}) };
+    })
+        .filter((item) => item != null);
+}
+function normalizePlannerTarget(value) {
+    if (!value || typeof value !== 'object')
+        return { channelId: null, agentId: null, targetType: 'general' };
+    const record = value;
+    const type = normalizePlannerString(record.type, 40).toLowerCase();
+    const agentId = normalizePlannerString(record.agentId ?? record.agent_id, 200) || null;
+    const channelId = normalizePlannerString(record.channelId ?? record.channel_id, 200) || null;
+    if (type === 'dm' && agentId)
+        return { channelId: `dm:${agentId}`, agentId, targetType: 'dm' };
+    if (type === 'channel' && channelId)
+        return { channelId, agentId: null, targetType: 'channel' };
+    if (channelId?.startsWith('dm:'))
+        return { channelId, agentId: agentId ?? channelId.slice(3), targetType: 'dm' };
+    if (channelId)
+        return { channelId, agentId: null, targetType: 'channel' };
+    if (agentId)
+        return { channelId: `dm:${agentId}`, agentId, targetType: 'dm' };
+    return { channelId: null, agentId: null, targetType: type || 'general' };
+}
+function plannerDedupeHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 24);
+}
+export function parseSuggestedPlannerOutput(raw) {
+    const parsed = parseJsonRecord(raw);
+    if (!parsed)
+        return { opportunities: [], error: 'Suggested planner returned invalid JSON.' };
+    if (!Object.prototype.hasOwnProperty.call(parsed, 'opportunities')) {
+        return { opportunities: [], error: 'Suggested planner JSON is missing opportunities array.' };
+    }
+    if (!Array.isArray(parsed.opportunities)) {
+        return { opportunities: [], error: 'Suggested planner JSON has invalid opportunities array.' };
+    }
+    const rawOpportunities = parsed.opportunities;
+    if (rawOpportunities.length === 0)
+        return { opportunities: [] };
+    const opportunities = [];
+    for (const item of rawOpportunities.slice(0, 8)) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        const title = normalizePlannerString(record.title, 160);
+        const rationale = normalizePlannerString(record.rationale, 800);
+        const suggestedAction = normalizePlannerString(record.suggestedAction ?? record.suggested_action, 500);
+        if (!title || !rationale)
+            continue;
+        const target = normalizePlannerTarget(record.target);
+        opportunities.push({
+            title,
+            rationale,
+            suggestedAction: suggestedAction || title,
+            priority: normalizePriority(record.priority),
+            channelId: target.channelId,
+            agentId: target.agentId,
+            targetType: target.targetType,
+            evidenceLinks: normalizeEvidenceLinks(record.evidenceLinks ?? record.evidence_links),
+        });
+    }
+    if (opportunities.length === 0)
+        return { opportunities, error: 'Suggested planner returned no valid opportunities.' };
+    return { opportunities };
+}
+export class SuggestedPlannerService {
+    db;
+    conversationManager;
+    nodeRegistry;
+    workspaceRoot;
+    constructor(db, conversationManager, nodeRegistry, workspaceRoot) {
+        this.db = db;
+        this.conversationManager = conversationManager;
+        this.nodeRegistry = nodeRegistry;
+        this.workspaceRoot = workspaceRoot;
+    }
+    getConfig(userId) {
+        const row = this.db.prepare(`SELECT user_id as userId, planner_agent_id as plannerAgentId, node_id as nodeId,
+              schedule_interval_ms as scheduleIntervalMs, lookback_days as lookbackDays,
+              last_run_at as lastRunAt, next_run_at as nextRunAt, enabled,
+              created_at as createdAt, updated_at as updatedAt
+         FROM suggested_planner_configs
+        WHERE user_id = ?`).get(userId);
+        return row ? mapConfigRow(row) : null;
+    }
+    async ensureConfigForUser(params) {
+        const existing = this.getConfig(params.userId);
+        if (existing)
+            return this.syncExistingConfigForUser({ ...params, existing });
+        const now = Date.now();
+        const nodeId = pickPlannerNodeId(this.nodeRegistry);
+        const plannerAgentId = randomUUID();
+        const workspacePath = buildPlannerWorkspacePath(this.workspaceRoot, params.username);
+        const envVars = buildPlannerEnvVars();
+        fs.mkdirSync(workspacePath, { recursive: true });
+        this.db.prepare(`INSERT INTO agents(
+         agent_id, name, agent_type, agent_role, model, reasoning_effort, claude_permission_mode,
+         codex_mode, codex_service_tier, channel_id, system_prompt, description, memory,
+         env_vars, disabled_tool_kinds, node_id, workspace_path, project_path, skill_roots,
+         created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(plannerAgentId, SUGGESTED_PLANNER_AGENT_NAME, 'claude_sdk', 'platform_agent', envVars.ANTHROPIC_MODEL ?? 'deepseek-v4-pro', null, 'bypassPermissions', null, null, 'default', '', 'System workbench agent that proposes proactive next work from tasks and chat context.', '', Object.keys(envVars).length > 0 ? JSON.stringify(envVars) : null, PLANNER_DISABLED_TOOL_KINDS_JSON, nodeId, workspacePath, null, null, now, now);
+        this.db.prepare(`INSERT OR IGNORE INTO agent_channel_memberships(agent_id, channel_id, is_home, joined_at)
+       VALUES(?, 'default', 1, ?)`).run(plannerAgentId, now);
+        this.db.prepare(`INSERT OR IGNORE INTO user_agent_access(user_id, agent_id, granted_at) VALUES(?, ?, ?)`).run(params.userId, plannerAgentId, now);
+        this.db.prepare(`INSERT INTO suggested_planner_configs(
+         user_id, planner_agent_id, node_id, schedule_interval_ms, lookback_days,
+         last_run_at, next_run_at, enabled, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, NULL, ?, 1, ?, ?)`).run(params.userId, plannerAgentId, nodeId, DEFAULT_SUGGESTED_PLANNER_INTERVAL_MS, DEFAULT_LOOKBACK_DAYS, now + DEFAULT_SUGGESTED_PLANNER_INTERVAL_MS, now, now);
+        const created = this.getConfig(params.userId);
+        if (!created)
+            throw new Error('Failed to create suggested planner config');
+        this.syncPlatformAgentInstance(created);
+        return created;
+    }
+    syncExistingConfigForUser(params) {
+        const nodeId = this.resolvePlannerNodeId(params.existing.nodeId);
+        const workspacePath = buildPlannerWorkspacePath(this.workspaceRoot, params.username);
+        fs.mkdirSync(workspacePath, { recursive: true });
+        const agentRow = this.db.prepare(`SELECT system_prompt as systemPrompt, workspace_path as workspacePath, disabled_tool_kinds as disabledToolKindsJson FROM agents WHERE agent_id = ?`).get(params.existing.plannerAgentId);
+        const assignmentChanged = nodeId !== params.existing.nodeId
+            || path.resolve(agentRow?.workspacePath ?? '') !== path.resolve(workspacePath);
+        const hasPersistedSystemPrompt = Boolean(agentRow?.systemPrompt?.trim());
+        const disabledToolKindsChanged = agentRow?.disabledToolKindsJson !== PLANNER_DISABLED_TOOL_KINDS_JSON;
+        if ((hasPersistedSystemPrompt || disabledToolKindsChanged) && !assignmentChanged) {
+            this.db.prepare(`UPDATE agents
+            SET system_prompt = '',
+                disabled_tool_kinds = ?,
+                updated_at = ?
+          WHERE agent_id = ?`).run(PLANNER_DISABLED_TOOL_KINDS_JSON, Date.now(), params.existing.plannerAgentId);
+        }
+        if (assignmentChanged || disabledToolKindsChanged) {
+            const now = Date.now();
+            this.db.prepare(`UPDATE suggested_planner_configs
+            SET node_id = ?,
+                updated_at = ?
+          WHERE user_id = ?`).run(nodeId, now, params.userId);
+            this.db.prepare(`UPDATE agents
+            SET node_id = ?,
+                workspace_path = ?,
+                system_prompt = '',
+                disabled_tool_kinds = ?,
+                updated_at = ?
+          WHERE agent_id = ?`).run(nodeId, workspacePath, PLANNER_DISABLED_TOOL_KINDS_JSON, now, params.existing.plannerAgentId);
+            this.db.prepare(`UPDATE conversations
+            SET node_id = ?,
+                workspace_path = ?,
+                updated_at = ?
+          WHERE agent_id = ?`).run(nodeId, workspacePath, now, params.existing.plannerAgentId);
+        }
+        const synced = this.getConfig(params.userId) ?? params.existing;
+        this.syncPlatformAgentInstance(synced);
+        return synced;
+    }
+    resolvePlannerNodeId(currentNodeId) {
+        const normalizedCurrentNodeId = currentNodeId?.trim() || null;
+        const preferredNodeId = pickPlannerNodeId(this.nodeRegistry);
+        if (preferredNodeId === 'local-node-1' && normalizedCurrentNodeId !== preferredNodeId) {
+            return preferredNodeId;
+        }
+        if (normalizedCurrentNodeId) {
+            const currentNode = this.nodeRegistry.getNode(normalizedCurrentNodeId);
+            if (currentNode?.agentTypes.includes('claude_sdk') && !normalizedCurrentNodeId.startsWith('scenario-')) {
+                return normalizedCurrentNodeId;
+            }
+        }
+        return preferredNodeId ?? normalizedCurrentNodeId;
+    }
+    getPlannerAgent(userId) {
+        const config = this.getConfig(userId);
+        if (!config || typeof this.conversationManager.getAgent !== 'function')
+            return null;
+        return this.conversationManager.getAgent(config.plannerAgentId);
+    }
+    syncPlatformAgentInstance(config) {
+        const agent = this.getPlannerAgent(config.userId);
+        try {
+            this.db.prepare(`INSERT INTO platform_agent_instances(
+           user_id, definition_id, agent_id, enabled, schedule_interval_ms,
+           workflow_config_json, runtime_config_json, last_run_at, next_run_at,
+           created_at, updated_at
+         ) VALUES(?, 'suggested_planner', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(user_id, definition_id) DO UPDATE SET
+           agent_id = excluded.agent_id,
+           last_run_at = COALESCE(platform_agent_instances.last_run_at, excluded.last_run_at),
+           updated_at = excluded.updated_at`).run(config.userId, config.plannerAgentId, config.enabled ? 1 : 0, Math.max(60_000, config.scheduleIntervalMs), JSON.stringify({ lookbackDays: config.lookbackDays }), JSON.stringify({
+                model: agent?.model ?? null,
+                reasoningEffort: agent?.reasoningEffort ?? null,
+                envVars: agent?.envVars ?? {},
+            }), config.lastRunAt, config.nextRunAt, config.createdAt, Date.now());
+        }
+        catch {
+            // Older tests and pre-v124 schemas may not have the generic platform-agent tables yet.
+        }
+    }
+    openPlannerConversation(userId, mode = 'debug') {
+        const config = this.getConfig(userId);
+        if (!config)
+            return null;
+        const title = getPlatformAgentConversationTitle({
+            definitionId: 'suggested_planner',
+            mode,
+        });
+        return this.conversationManager.openNamedAgentPrimaryThread?.({
+            agentId: config.plannerAgentId,
+            title,
+            userId,
+            legacyTitles: mode === 'debug'
+                ? getPlatformAgentLegacyConversationTitles('suggested_planner')
+                : undefined,
+        }) ?? this.conversationManager.openAgentThread(config.plannerAgentId, userId);
+    }
+    updateConfig(userId, patch) {
+        const existing = this.getConfig(userId);
+        if (!existing)
+            throw new Error('Suggested planner config not found');
+        const now = Date.now();
+        const scheduleIntervalMs = Math.max(60_000, patch.scheduleIntervalMs ?? existing.scheduleIntervalMs);
+        const lookbackDays = Math.max(1, Math.min(90, Math.round(patch.lookbackDays ?? existing.lookbackDays)));
+        const enabled = patch.enabled ?? existing.enabled;
+        const nextRunAt = existing.nextRunAt ?? (now + scheduleIntervalMs);
+        this.db.prepare(`UPDATE suggested_planner_configs
+          SET schedule_interval_ms = ?,
+              lookback_days = ?,
+              enabled = ?,
+              next_run_at = ?,
+              updated_at = ?
+        WHERE user_id = ?`).run(scheduleIntervalMs, lookbackDays, enabled ? 1 : 0, nextRunAt, now, userId);
+        if (Object.prototype.hasOwnProperty.call(patch, 'model')
+            || Object.prototype.hasOwnProperty.call(patch, 'reasoningEffort')
+            || Object.prototype.hasOwnProperty.call(patch, 'envVars')) {
+            this.updatePlannerAgentRuntime(userId, patch);
+        }
+        const updated = this.getConfig(userId);
+        if (!updated)
+            throw new Error('Suggested planner config not found after update');
+        this.syncPlatformAgentInstance(updated);
+        return updated;
+    }
+    updatePlannerAgentRuntime(userId, patch) {
+        const config = this.getConfig(userId);
+        if (!config)
+            return null;
+        const existing = this.conversationManager.getAgent(config.plannerAgentId);
+        if (!existing)
+            return null;
+        const nextModel = Object.prototype.hasOwnProperty.call(patch, 'model')
+            ? patch.model?.trim() || null
+            : existing.model ?? null;
+        const nextReasoning = Object.prototype.hasOwnProperty.call(patch, 'reasoningEffort')
+            ? patch.reasoningEffort?.trim() || null
+            : existing.reasoningEffort ?? null;
+        const nextEnvVars = Object.prototype.hasOwnProperty.call(patch, 'envVars')
+            ? patch.envVars ?? {}
+            : existing.envVars ?? {};
+        const envVarsJson = Object.keys(nextEnvVars).length > 0 ? JSON.stringify(nextEnvVars) : null;
+        const now = Date.now();
+        this.db.prepare(`UPDATE agents
+          SET model = ?,
+              reasoning_effort = ?,
+              env_vars = ?,
+              disabled_tool_kinds = ?,
+              updated_at = ?
+        WHERE agent_id = ?`).run(nextModel, nextReasoning, envVarsJson, PLANNER_DISABLED_TOOL_KINDS_JSON, now, config.plannerAgentId);
+        this.db.prepare(`UPDATE conversations
+          SET env_vars = ?,
+              updated_at = ?
+        WHERE agent_id = ?`).run(envVarsJson, now, config.plannerAgentId);
+        const updatedAgent = this.conversationManager.getAgent(config.plannerAgentId);
+        this.syncPlatformAgentInstance(this.getConfig(userId) ?? config);
+        return updatedAgent;
+    }
+    listDueConfigs(now) {
+        const rows = this.db.prepare(`SELECT user_id as userId, planner_agent_id as plannerAgentId, node_id as nodeId,
+              schedule_interval_ms as scheduleIntervalMs, lookback_days as lookbackDays,
+              last_run_at as lastRunAt, next_run_at as nextRunAt, enabled,
+              created_at as createdAt, updated_at as updatedAt
+         FROM suggested_planner_configs
+        WHERE enabled = 1 AND next_run_at IS NOT NULL AND next_run_at <= ?`).all(now);
+        return rows.map(mapConfigRow);
+    }
+    getUsernameForUserId(userId) {
+        const row = this.db.prepare(`SELECT username FROM users WHERE id = ?`).get(userId);
+        return row?.username?.trim() || null;
+    }
+    getLastRun(userId) {
+        this.reconcileCompletedRunningRuns(userId);
+        this.unblockRunningPlannerHost(userId);
+        const row = this.db.prepare(`SELECT run_id as runId, status, created_at as createdAt, completed_at as completedAt, error,
+              generated_count as generatedCount
+         FROM suggested_planner_runs
+        WHERE user_id = ?
+        ORDER BY created_at DESC
+        LIMIT 1`).get(userId);
+        return row ?? null;
+    }
+    async dispatchPlanRun(params) {
+        const config = await this.ensureConfigForUser({ userId: params.userId, username: params.username });
+        if (!config.enabled && !params.manual) {
+            return { ok: true, skipped: true, reason: 'Suggested planner is disabled' };
+        }
+        this.reconcileCompletedRunningRuns(params.userId);
+        this.unblockRunningPlannerHost(params.userId);
+        const running = this.db.prepare(`SELECT run_id as runId FROM suggested_planner_runs
+       WHERE user_id = ? AND status = 'running'
+       ORDER BY created_at DESC LIMIT 1`).get(params.userId);
+        if (running) {
+            return { ok: true, skipped: true, queued: true, runId: running.runId, reason: 'Suggested planner run already in progress' };
+        }
+        this.clearOrphanActivePlannerConversation({
+            userId: params.userId,
+            plannerAgentId: config.plannerAgentId,
+        });
+        const snapshot = this.buildSnapshot(params.userId, params.username, config);
+        const conversation = this.openPlannerConversation(params.userId, 'workflow');
+        if (!conversation)
+            return { ok: false, error: 'Failed to open planner conversation' };
+        const prompt = this.buildPlannerPrompt({ config, snapshot });
+        const activationMetadata = {
+            platformRun: {
+                definitionId: 'suggested_planner',
+                workflowType: 'planner_suggestions',
+                mode: 'workflow',
+            },
+            suppressReplyContract: true,
+        };
+        const result = await this.conversationManager.submitPrompt(conversation.id, prompt, {
+            recordAsUserMessage: false,
+            activationMetadata,
+            suppressReplyContract: true,
+        });
+        const now = Date.now();
+        if (!result.runId) {
+            this.scheduleNextRun(params.userId, now);
+            return { ok: false, error: 'Failed to start suggested planner run', queued: result.queued, generatedCount: 0 };
+        }
+        this.db.prepare(`INSERT INTO suggested_planner_runs(run_id, user_id, status, created_at, generated_count)
+       VALUES(?, ?, 'running', ?, ?)`).run(result.runId, params.userId, now, 0);
+        this.db.prepare(`UPDATE suggested_planner_configs SET last_run_at = ?, updated_at = ? WHERE user_id = ?`).run(now, now, params.userId);
+        await this.reconcileRunStateAfterInsert(result.runId, params.userId);
+        return { ok: true, runId: result.runId, queued: result.queued, generatedCount: 0 };
+    }
+    async finalizePlanRun(params) {
+        this.finalizePlanRunNow(params);
+    }
+    finalizePlanRunNow(params) {
+        const row = this.db.prepare(`SELECT run_id as runId, status FROM suggested_planner_runs WHERE run_id = ?`).get(params.runId);
+        if (!row || row.status !== 'running')
+            return;
+        const now = Date.now();
+        let error = params.error;
+        let generatedCount = 0;
+        if (!error) {
+            const ingestResult = this.ingestPlannerRunOutput({
+                userId: params.userId,
+                runId: params.runId,
+                now,
+            });
+            generatedCount = ingestResult.generatedCount;
+            error = ingestResult.error;
+        }
+        this.db.prepare(`UPDATE suggested_planner_runs
+          SET status = ?,
+              completed_at = ?,
+              error = ?,
+              generated_count = ?
+        WHERE run_id = ?`).run(error ? 'failed' : 'completed', now, error ?? null, generatedCount, params.runId);
+        this.scheduleNextRun(params.userId, now);
+    }
+    reconcileCompletedRunningRuns(userId) {
+        const rows = this.db.prepare(`SELECT spr.run_id as runId,
+              spr.user_id as userId,
+              r.stop_reason as stopReason,
+              r.error as error
+         FROM suggested_planner_runs spr
+         JOIN runs r ON r.run_id = spr.run_id
+        WHERE spr.status = 'running'
+          AND r.ended_at IS NOT NULL
+          ${userId ? 'AND spr.user_id = ?' : ''}`).all(...(userId ? [userId] : []));
+        for (const row of rows) {
+            this.finalizePlanRunNow({
+                runId: row.runId,
+                userId: row.userId,
+                error: getSuggestedPlannerTerminalError(row.stopReason, row.error),
+            });
+        }
+    }
+    clearOrphanActivePlannerConversation(params) {
+        const workflowTitle = getPlatformAgentConversationTitle({
+            definitionId: 'suggested_planner',
+            mode: 'workflow',
+        });
+        const rows = this.db.prepare(`SELECT c.id as conversationId,
+              c.session_key as sessionKey,
+              c.agent_type as agentType,
+              r.run_id as runId,
+              h.current_run_id as snapshotRunId
+         FROM conversations c
+         LEFT JOIN runs r ON r.session_key = c.session_key AND r.ended_at IS NULL
+         LEFT JOIN node_host_snapshots h
+           ON h.node_id = c.node_id
+          AND h.host_key = 'conversation:' || c.id || ':' || c.agent_type
+          AND h.state = 'active'
+          AND h.current_run_id IS NOT NULL
+        WHERE c.agent_id = ?
+          AND c.user_id = ?
+          AND c.title = ?
+          AND c.status IN ('queued', 'active', 'recovering', 'awaiting_approval')
+          AND NOT EXISTS (
+            SELECT 1
+              FROM suggested_planner_runs spr
+             WHERE spr.run_id = COALESCE(h.current_run_id, r.run_id)
+               AND spr.status = 'running'
+          )`).all(params.plannerAgentId, params.userId, workflowTitle);
+        if (rows.length === 0)
+            return;
+        for (const row of rows) {
+            this.conversationManager.cancelConversationRun(row.conversationId, row.snapshotRunId ?? row.runId ?? undefined);
+        }
+        const now = Date.now();
+        const transaction = this.db.transaction(() => {
+            for (const row of rows) {
+                if (row.snapshotRunId) {
+                    this.db.prepare(`DELETE FROM node_dispatch_queue WHERE run_id = ?`).run(row.snapshotRunId);
+                    this.db.prepare(`UPDATE runs
+                SET ended_at = COALESCE(ended_at, ?),
+                    error = COALESCE(error, ?)
+              WHERE run_id = ?
+                AND ended_at IS NULL`).run(now, 'Superseded by a new Suggested Planner run', row.snapshotRunId);
+                }
+                else if (row.sessionKey) {
+                    this.db.prepare(`DELETE FROM node_dispatch_queue WHERE conversation_id = ?`).run(row.conversationId);
+                    this.db.prepare(`UPDATE runs
+                SET ended_at = COALESCE(ended_at, ?),
+                    error = COALESCE(error, ?)
+              WHERE session_key = ?
+                AND ended_at IS NULL`).run(now, 'Superseded by a new Suggested Planner run', row.sessionKey);
+                }
+                this.db.prepare(`DELETE FROM conversation_prompt_queue WHERE conversation_id = ?`).run(row.conversationId);
+                this.db.prepare(`DELETE FROM node_host_snapshots
+            WHERE host_key = ?`).run(`conversation:${row.conversationId}:${row.agentType}`);
+                this.db.prepare(`UPDATE conversations
+              SET status = 'idle',
+                  updated_at = ?
+            WHERE id = ?`).run(now, row.conversationId);
+            }
+        });
+        transaction();
+    }
+    unblockRunningPlannerHost(userId) {
+        const rows = this.db.prepare(`SELECT c.id as conversationId,
+              h.current_run_id as snapshotRunId,
+              h.host_key as hostKey,
+              h.node_id as nodeId
+         FROM suggested_planner_runs spr
+         JOIN runs running_run ON running_run.run_id = spr.run_id
+         JOIN conversations c ON c.session_key = running_run.session_key
+         JOIN node_host_snapshots h
+           ON h.node_id = c.node_id
+          AND h.host_key = 'conversation:' || c.id || ':' || c.agent_type
+          AND h.state = 'active'
+          AND h.current_run_id IS NOT NULL
+         LEFT JOIN suggested_planner_runs current_spr
+           ON current_spr.run_id = h.current_run_id
+          AND current_spr.status = 'running'
+        WHERE spr.user_id = ?
+          AND spr.status = 'running'
+          AND h.current_run_id != spr.run_id
+          AND current_spr.run_id IS NULL`).all(userId);
+        if (rows.length === 0)
+            return;
+        const now = Date.now();
+        const transaction = this.db.transaction(() => {
+            for (const row of rows) {
+                this.conversationManager.cancelConversationRun(row.conversationId, row.snapshotRunId);
+                this.db.prepare(`DELETE FROM node_dispatch_queue WHERE run_id = ?`).run(row.snapshotRunId);
+                this.db.prepare(`UPDATE runs
+              SET ended_at = COALESCE(ended_at, ?),
+                  error = COALESCE(error, ?)
+            WHERE run_id = ?
+              AND ended_at IS NULL`).run(now, 'Superseded by a newer Suggested Planner run', row.snapshotRunId);
+                this.db.prepare(`DELETE FROM node_host_snapshots
+            WHERE node_id = ?
+              AND host_key = ?
+              AND current_run_id = ?`).run(row.nodeId, row.hostKey, row.snapshotRunId);
+            }
+        });
+        transaction();
+    }
+    async reconcileRunStateAfterInsert(runId, userId) {
+        const runRow = this.db.prepare(`SELECT ended_at as endedAt, stop_reason as stopReason, error
+       FROM runs
+       WHERE run_id = ?`).get(runId);
+        if (!runRow?.endedAt)
+            return;
+        this.finalizePlanRunNow({
+            runId,
+            userId,
+            error: getSuggestedPlannerTerminalError(runRow.stopReason, runRow.error),
+        });
+    }
+    scheduleNextRun(userId, now) {
+        const config = this.getConfig(userId);
+        if (!config)
+            return;
+        this.db.prepare(`UPDATE suggested_planner_configs SET next_run_at = ?, updated_at = ? WHERE user_id = ?`).run(now + config.scheduleIntervalMs, now, userId);
+    }
+    buildSnapshot(userId, username, config) {
+        const since = Date.now() - config.lookbackDays * 24 * 60 * 60 * 1000;
+        const directTarget = `dm:@${username}`;
+        const directThreadTargetGlob = `${directTarget}:*`;
+        const tasks = this.db.prepare(`SELECT t.task_id as taskId, t.channel_id as channelId, t.task_number as taskNumber,
+              t.title, t.description, t.status, t.updated_at as updatedAt,
+              t.claimed_by_name as assigneeName, c.name as channelName, a.name as agentName,
+              CASE WHEN t.channel_id LIKE 'dm:%' THEN 'dm' ELSE 'channel' END as sourceType
+         FROM tasks t
+         LEFT JOIN channel_messages cm ON cm.message_id = t.message_id
+         LEFT JOIN channels c ON c.channel_id = t.channel_id
+         LEFT JOIN agents a ON a.agent_id = substr(t.channel_id, 4)
+        WHERE t.status != 'done'
+          AND (
+            (t.channel_id NOT LIKE 'dm:%' AND EXISTS (
+              SELECT 1 FROM user_channel_access uca WHERE uca.channel_id = t.channel_id AND uca.user_id = ?
+            ))
+            OR (t.channel_id LIKE 'dm:%' AND EXISTS (
+              SELECT 1 FROM user_agent_access uaa WHERE uaa.user_id = ? AND uaa.agent_id = substr(t.channel_id, 4)
+            ) AND COALESCE(NULLIF(t.dm_target, ''), cm.target) = ?)
+          )
+        ORDER BY t.updated_at DESC
+        LIMIT 40`).all(userId, userId, directTarget);
+        const saved = this.db.prepare(`SELECT id, sender_name as senderName, content, context_url as contextUrl, source_kind as sourceKind, created_at as createdAt
+         FROM saved_items
+        WHERE user_id = ? AND process_status = 'inbox'
+        ORDER BY created_at DESC
+        LIMIT 20`).all(userId);
+        const summaries = this.db.prepare(`SELECT cs.conversation_id as conversationId, cs.reply_target as replyTarget,
+              cs.summary_json as summaryJson, cs.updated_at as updatedAt
+         FROM conversation_summaries cs
+         JOIN conversations conv ON conv.id = cs.conversation_id
+        WHERE conv.user_id = ?
+          AND cs.updated_at >= ?
+        ORDER BY cs.updated_at DESC
+        LIMIT 20`).all(userId, since);
+        const recentMessages = this.db.prepare(`SELECT message_id as messageId, channel_id as channelId, sender_name as senderName,
+              target, content, created_at as createdAt
+         FROM channel_messages
+        WHERE created_at >= ?
+          AND (
+            (channel_id NOT LIKE 'dm:%' AND EXISTS (
+              SELECT 1 FROM user_channel_access uca WHERE uca.channel_id = channel_messages.channel_id AND uca.user_id = ?
+            ))
+            OR (channel_id LIKE 'dm:%' AND EXISTS (
+              SELECT 1 FROM user_agent_access uaa WHERE uaa.user_id = ? AND uaa.agent_id = substr(channel_id, 4)
+            ) AND (target = ? OR target GLOB ?))
+          )
+        ORDER BY created_at DESC
+        LIMIT 30`).all(since, userId, userId, directTarget, directThreadTargetGlob);
+        const mappedSummaries = summaries.map((summary) => ({
+            conversationId: summary.conversationId,
+            replyTarget: summary.replyTarget,
+            updatedAt: summary.updatedAt,
+            summary: parseJsonObject(String(summary.summaryJson ?? '')),
+        }));
+        return { tasks, saved, summaries: mappedSummaries, recentMessages };
+    }
+    getPlannerRunOutputText(runId) {
+        const rows = this.db.prepare(`SELECT payload_json as payloadJson
+         FROM events
+        WHERE run_id = ?
+          AND method = 'node/event'
+          AND json_valid(payload_json)
+          AND json_extract(payload_json, '$.type') IN ('content.delta', 'activity.delta')
+        ORDER BY seq ASC`).all(runId);
+        const byType = { 'content.delta': [], 'activity.delta': [] };
+        for (const row of rows) {
+            try {
+                const payload = JSON.parse(row.payloadJson);
+                if (typeof payload.type === 'string' && typeof payload.text === 'string') {
+                    byType[payload.type]?.push(payload.text);
+                }
+            }
+            catch {
+                // Ignore malformed historical rows; invalid output is handled by the parser.
+            }
+        }
+        const contentText = byType['content.delta'].join('').trim();
+        return contentText || byType['activity.delta'].join('').trim();
+    }
+    ingestPlannerRunOutput(params) {
+        const outputText = this.getPlannerRunOutputText(params.runId);
+        const parsed = parseSuggestedPlannerOutput(outputText);
+        if (parsed.error)
+            return { generatedCount: 0, error: parsed.error };
+        let generatedCount = 0;
+        const seenKeys = new Set();
+        for (const opportunity of parsed.opportunities) {
+            const target = this.resolveAccessiblePlannerTarget(params.userId, opportunity);
+            const dedupePayload = [
+                opportunity.title.toLowerCase(),
+                target.targetType,
+                target.channelId ?? '',
+                target.agentId ?? '',
+                opportunity.evidenceLinks.map((link) => link.url).join('|'),
+            ].join('\n');
+            const dedupeKey = `planner:v2:${plannerDedupeHash(dedupePayload)}`;
+            if (seenKeys.has(dedupeKey))
+                continue;
+            seenKeys.add(dedupeKey);
+            insertPlannerTaskCandidateOpportunity(this.db, {
+                userId: params.userId,
+                dedupeKey,
+                title: opportunity.title,
+                rationale: opportunity.rationale,
+                channelId: target.channelId,
+                agentId: target.agentId,
+                evidence: {
+                    source: 'suggested_planner',
+                    plannerRunId: params.runId,
+                    priority: opportunity.priority,
+                    targetType: target.targetType,
+                    channelId: target.channelId,
+                    agentId: target.agentId,
+                    requestedTargetType: opportunity.targetType,
+                    requestedChannelId: opportunity.channelId,
+                    requestedAgentId: opportunity.agentId,
+                    suggestedTitle: opportunity.title,
+                    suggestedDescription: opportunity.suggestedAction || opportunity.rationale,
+                    suggestedAction: opportunity.suggestedAction,
+                },
+                evidenceLinks: opportunity.evidenceLinks,
+                now: params.now,
+            });
+            generatedCount += 1;
+        }
+        return { generatedCount };
+    }
+    resolveAccessiblePlannerTarget(userId, opportunity) {
+        const agentId = opportunity.agentId?.trim() || null;
+        const channelId = opportunity.channelId?.trim() || null;
+        if (agentId && this.userCanAccessAgent(userId, agentId)) {
+            return { channelId: `dm:${agentId}`, agentId, targetType: 'dm' };
+        }
+        if (channelId?.startsWith('dm:')) {
+            const dmAgentId = channelId.slice(3).trim();
+            if (dmAgentId && this.userCanAccessAgent(userId, dmAgentId)) {
+                return { channelId, agentId: dmAgentId, targetType: 'dm' };
+            }
+            return { channelId: null, agentId: null, targetType: 'general' };
+        }
+        if (channelId && this.userCanAccessChannel(userId, channelId)) {
+            return { channelId, agentId: null, targetType: 'channel' };
+        }
+        return { channelId: null, agentId: null, targetType: 'general' };
+    }
+    userCanAccessAgent(userId, agentId) {
+        return Boolean(this.db.prepare(`SELECT 1
+         FROM agents a
+         JOIN user_agent_access uaa ON uaa.agent_id = a.agent_id
+        WHERE a.agent_id = ?
+          AND a.deleted_at IS NULL
+          AND uaa.user_id = ?
+        LIMIT 1`).get(agentId, userId));
+    }
+    userCanAccessChannel(userId, channelId) {
+        return Boolean(this.db.prepare(`SELECT 1
+         FROM channels c
+         JOIN user_channel_access uca ON uca.channel_id = c.channel_id
+        WHERE c.channel_id = ?
+          AND uca.user_id = ?
+        LIMIT 1`).get(channelId, userId));
+    }
+    buildPlannerPrompt(params) {
+        return [
+            '# Suggested Planner run',
+            '',
+            `Lookback days: ${params.config.lookbackDays}`,
+            '',
+            'Review the JSON snapshot and propose concrete next work. The platform will only surface suggestions for user confirmation.',
+            'Do not execute the work. Do not create tasks yourself.',
+            '',
+            'Return only a JSON object. Do not include markdown, comments, or prose outside the JSON.',
+            'Schema:',
+            '{',
+            '  "opportunities": [',
+            '    {',
+            '      "title": "short task candidate title",',
+            '      "rationale": "why this likely matters now",',
+            '      "suggestedAction": "what task should be created if the user accepts",',
+            '      "priority": "high | medium | low",',
+            '      "target": { "type": "dm | channel | general", "agentId": "optional agent id", "channelId": "optional channel id" },',
+            '      "evidenceLinks": [{ "label": "source label", "url": "app-relative or absolute URL", "summary": "short source summary" }]',
+            '    }',
+            '  ]',
+            '}',
+            '',
+            'Rules:',
+            '- Include at most 8 opportunities.',
+            '- Prefer concrete follow-ups backed by tasks, summaries, saved inbox items, or recent messages.',
+            '- Use target.type "dm" only when the target agent id is known; use "channel" only when channel id is known; otherwise use "general".',
+            '- If there is no meaningful next work, return {"opportunities":[]}.',
+            '',
+            '```json',
+            JSON.stringify(params.snapshot, null, 2),
+            '```',
+        ].join('\n');
+    }
+}
+export function getSuggestedPlannerTerminalError(stopReason, error) {
+    const explicitError = error?.trim();
+    if (explicitError)
+        return explicitError;
+    const normalized = stopReason?.trim().toLowerCase();
+    if (!normalized || normalized === 'end_turn' || normalized === 'stop_sequence')
+        return undefined;
+    if (normalized.includes('cancel') || normalized.includes('abort') || normalized === 'error') {
+        return `Suggested planner run ended before completion: ${stopReason}`;
+    }
+    return undefined;
+}
+export function isPlatformAgent(agent) {
+    return agent?.agentRole === 'platform_agent' || agent?.agentRole === 'library_curator' || agent?.agentRole === 'suggested_planner';
+}