@bbigbang/core 0.1.0

package/dist/services/platformAgentService.js

@@ -0,0 +1,2041 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { log } from '@bbigbang/runtime-acp';
+import { insertPlannerTaskCandidateOpportunity } from '../web/proactiveOpportunities.js';
+import { getLibraryCuratorTerminalError, } from './libraryService.js';
+import { getBuiltinPlatformDefinition, getPlatformAgentConversationTitle, getPlatformAgentLegacyConversationTitles, getPlatformWorkflowCatalog, getPlatformWorkflowCatalogEntry, isBuiltinPlatformAgentDefinitionId, normalizePlatformAgentToolPolicy, normalizePlatformResourceScopes, } from './platformAgentPolicy.js';
+import { getSuggestedPlannerTerminalError, parseSuggestedPlannerOutput, } from './suggestedPlannerService.js';
+const DEFAULT_PLATFORM_AGENT_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_LOOKBACK_DAYS = 14;
+const PLATFORM_AGENT_WORKSPACE_DIRECTORY_NAME = '.platform-agents';
+const PLANNER_WORKSPACE_DIRECTORY_NAME = '.suggested-planner';
+const LIBRARY_ROOT_DIRECTORY_NAME = '.library-curator';
+const CURATOR_WORKSPACE_DIRECTORY_NAME = 'workspaces';
+const PLATFORM_AGENT_TYPE = 'claude_sdk';
+const LEGACY_SUGGESTED_PLANNER_PROMPT_PREFIX = '# Suggested Planner run';
+const LEGACY_SUGGESTED_PLANNER_CLEANUP_ERROR = 'Legacy Suggested Planner workflow run was cleaned up after the platform-agent migration.';
+export function getPlatformWorkflowTerminalError(workflowType, stopReason, error) {
+    if (workflowType === 'planner_suggestions') {
+        return getSuggestedPlannerTerminalError(stopReason, error);
+    }
+    return getLibraryCuratorTerminalError(stopReason, error);
+}
+function safeUsername(username) {
+    return username.replace(/[^a-zA-Z0-9._-]+/g, '_').trim() || 'user';
+}
+function parseJsonRecord(raw) {
+    if (!raw?.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseJsonStringArray(raw) {
+    if (!raw?.trim())
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === 'string' && item.trim().length > 0).map((item) => item.trim())
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function mapDefinitionRow(row) {
+    return {
+        definitionId: row.definitionId,
+        workflowType: row.workflowType,
+        label: row.label,
+        description: row.description,
+        resourceScopes: normalizePlatformResourceScopes(row.workflowType, parseJsonStringArray(row.resourceScopesJson)),
+        resourceConfig: parseJsonRecord(row.resourceConfigJson),
+        promptTemplateOverride: row.promptTemplateOverride,
+        toolPolicy: normalizePlatformAgentToolPolicy(row.workflowType, parseJsonRecord(row.toolPolicyJson)),
+        enabled: row.enabled === 1,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+function mapInstanceRow(row) {
+    const runtimeConfigRecord = parseJsonRecord(row.runtimeConfigJson);
+    return {
+        userId: row.userId,
+        definitionId: row.definitionId,
+        agentId: row.agentId,
+        enabled: row.enabled === 1,
+        scheduleIntervalMs: row.scheduleIntervalMs,
+        workflowConfig: parseJsonRecord(row.workflowConfigJson),
+        runtimeConfig: {
+            model: typeof runtimeConfigRecord.model === 'string' ? runtimeConfigRecord.model : null,
+            reasoningEffort: typeof runtimeConfigRecord.reasoningEffort === 'string' ? runtimeConfigRecord.reasoningEffort : null,
+            envVars: normalizeEnvVars(runtimeConfigRecord.envVars),
+        },
+        lastRunAt: row.lastRunAt,
+        nextRunAt: row.nextRunAt,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+function mapRunRow(row) {
+    let resourcesAccessed = null;
+    if (row.resourcesAccessedJson) {
+        try {
+            const parsed = JSON.parse(row.resourcesAccessedJson);
+            if (parsed &&
+                typeof parsed === 'object' &&
+                !Array.isArray(parsed) &&
+                typeof parsed.savedItems === 'number' &&
+                typeof parsed.tasks === 'number' &&
+                typeof parsed.messages === 'number') {
+                resourcesAccessed = parsed;
+            }
+        }
+        catch {
+            // ignore invalid JSON
+        }
+    }
+    return {
+        runId: row.runId,
+        definitionId: row.definitionId,
+        userId: row.userId,
+        mode: row.mode,
+        status: row.status,
+        createdAt: row.createdAt,
+        completedAt: row.completedAt,
+        error: row.error,
+        generatedCount: row.generatedCount,
+        resourcesAccessed,
+    };
+}
+function normalizeEnvVars(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === 'string')
+            out[key] = raw;
+    }
+    return out;
+}
+function buildPlannerWorkspacePath(workspaceRoot, username) {
+    return path.join(workspaceRoot, PLANNER_WORKSPACE_DIRECTORY_NAME, safeUsername(username));
+}
+function buildCuratorWorkspacePath(workspaceRoot, username) {
+    return path.join(workspaceRoot, LIBRARY_ROOT_DIRECTORY_NAME, CURATOR_WORKSPACE_DIRECTORY_NAME, safeUsername(username));
+}
+function buildGenericPlatformWorkspacePath(workspaceRoot, definitionId, username) {
+    return path.join(workspaceRoot, PLATFORM_AGENT_WORKSPACE_DIRECTORY_NAME, definitionId, 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 buildCuratorEnvVars() {
+    const envVars = {};
+    const baseUrl = process.env.LIBRARY_CURATOR_ANTHROPIC_BASE_URL?.trim()
+        || process.env.ANTHROPIC_BASE_URL?.trim();
+    const model = process.env.LIBRARY_CURATOR_ANTHROPIC_MODEL?.trim()
+        || process.env.ANTHROPIC_MODEL?.trim()
+        || 'deepseek-v4-pro';
+    const authToken = process.env.LIBRARY_CURATOR_ANTHROPIC_AUTH_TOKEN?.trim()
+        || process.env.LIBRARY_CURATOR_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 pickLibraryNodeId(nodeRegistry) {
+    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 plannerDedupeHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 24);
+}
+function normalizePlannerString(value, limit) {
+    return String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, 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 || !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 sanitizeDefinitionId(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error('Definition id is required.');
+    if (!/^[a-z0-9._-]+$/.test(trimmed))
+        throw new Error('Definition id may contain only lowercase letters, numbers, ".", "_" and "-".');
+    return trimmed;
+}
+function parseCuratorPlan(raw) {
+    const parsed = parseJsonRecord(raw);
+    if (!Array.isArray(parsed.operations)) {
+        throw new Error('Library curator JSON is missing operations array.');
+    }
+    if (!Array.isArray(parsed.processedSavedItemIds)) {
+        throw new Error('Library curator JSON is missing processedSavedItemIds array.');
+    }
+    const operations = parsed.operations.map((item) => {
+        if (!item || typeof item !== 'object') {
+            throw new Error('Library curator operation must be an object.');
+        }
+        const record = item;
+        const kind = record.kind === 'create' || record.kind === 'update' ? record.kind : null;
+        const relativePath = normalizePlannerString(record.relativePath, 400);
+        const title = normalizePlannerString(record.title, 200);
+        const summary = normalizePlannerString(record.summary, 400);
+        const content = typeof record.content === 'string' ? record.content.replace(/\r\n/g, '\n') : '';
+        const sourceSavedItemIds = Array.isArray(record.sourceSavedItemIds)
+            ? record.sourceSavedItemIds.filter((value) => typeof value === 'string' && value.trim().length > 0).map((value) => value.trim())
+            : [];
+        if (!kind || !relativePath || !content.trim()) {
+            throw new Error('Library curator operation is missing required fields.');
+        }
+        return {
+            kind,
+            relativePath,
+            title: title || path.posix.basename(relativePath, path.posix.extname(relativePath)),
+            summary,
+            content,
+            sourceSavedItemIds,
+        };
+    });
+    const processedSavedItemIds = parsed.processedSavedItemIds
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .map((value) => value.trim());
+    return {
+        operations,
+        processedSavedItemIds: [...new Set(processedSavedItemIds)],
+    };
+}
+export class PlatformAgentService {
+    db;
+    conversationManager;
+    nodeRegistry;
+    workspaceBroker;
+    workspaceRoot;
+    libraryService;
+    suggestedPlannerService;
+    agentRuntimeCleanupBroker;
+    workflowHandlers;
+    constructor(db, conversationManager, nodeRegistry, workspaceBroker, workspaceRoot, libraryService, suggestedPlannerService, agentRuntimeCleanupBroker) {
+        this.db = db;
+        this.conversationManager = conversationManager;
+        this.nodeRegistry = nodeRegistry;
+        this.workspaceBroker = workspaceBroker;
+        this.workspaceRoot = workspaceRoot;
+        this.libraryService = libraryService;
+        this.suggestedPlannerService = suggestedPlannerService;
+        this.agentRuntimeCleanupBroker = agentRuntimeCleanupBroker;
+        this.workflowHandlers = {
+            planner_suggestions: {
+                workflowType: 'planner_suggestions',
+                defaultLabel: 'Planner Suggestions',
+                defaultDescription: 'Reviews operational context and proposes concrete follow-up opportunities.',
+                buildDefaultWorkflowConfig: () => ({ lookbackDays: DEFAULT_LOOKBACK_DAYS }),
+                buildPrompt: ({ definition, instance, snapshot }) => {
+                    const lookbackDays = this.getPlannerLookbackDays(instance.workflowConfig);
+                    const template = definition.promptTemplateOverride?.trim()
+                        || getPlatformWorkflowCatalogEntry('planner_suggestions').defaultPromptTemplate;
+                    return [
+                        '# Platform planner workflow run',
+                        '',
+                        `Definition: ${definition.label} (${definition.definitionId})`,
+                        `Lookback days: ${lookbackDays}`,
+                        '',
+                        template,
+                        '',
+                        '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 the provided resources.',
+                        '- 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({
+                            workflowConfig: { lookbackDays },
+                            resources: snapshot,
+                        }, null, 2),
+                        '```',
+                    ].join('\n');
+                },
+                finalize: async ({ userId, runId, rawOutputText }) => {
+                    const parsed = parseSuggestedPlannerOutput(rawOutputText);
+                    if (parsed.error)
+                        throw new Error(parsed.error);
+                    const now = Date.now();
+                    const opportunities = parsed.opportunities.map((opportunity) => {
+                        const target = this.resolveAccessiblePlannerTarget(userId, opportunity);
+                        const dedupePayload = [
+                            opportunity.title.toLowerCase(),
+                            target.targetType,
+                            target.channelId ?? '',
+                            target.agentId ?? '',
+                            opportunity.evidenceLinks.map((link) => link.url).join('|'),
+                        ].join('\n');
+                        return {
+                            dedupeKey: `planner:v2:${plannerDedupeHash(dedupePayload)}`,
+                            opportunity,
+                            target,
+                        };
+                    });
+                    const seenKeys = new Set();
+                    let generatedCount = 0;
+                    for (const item of opportunities) {
+                        if (seenKeys.has(item.dedupeKey))
+                            continue;
+                        seenKeys.add(item.dedupeKey);
+                        insertPlannerTaskCandidateOpportunity(this.db, {
+                            userId,
+                            dedupeKey: item.dedupeKey,
+                            title: item.opportunity.title,
+                            rationale: item.opportunity.rationale,
+                            channelId: item.target.channelId,
+                            agentId: item.target.agentId,
+                            evidence: {
+                                source: 'suggested_planner',
+                                plannerRunId: runId,
+                                priority: item.opportunity.priority,
+                                targetType: item.target.targetType,
+                                channelId: item.target.channelId,
+                                agentId: item.target.agentId,
+                                requestedTargetType: item.opportunity.targetType,
+                                requestedChannelId: item.opportunity.channelId,
+                                requestedAgentId: item.opportunity.agentId,
+                                suggestedTitle: item.opportunity.title,
+                                suggestedDescription: item.opportunity.suggestedAction || item.opportunity.rationale,
+                                suggestedAction: item.opportunity.suggestedAction,
+                            },
+                            evidenceLinks: item.opportunity.evidenceLinks,
+                            now,
+                        });
+                        generatedCount += 1;
+                    }
+                    return {
+                        outputJson: { opportunities: parsed.opportunities },
+                        resultJson: { generatedCount },
+                        generatedCount,
+                    };
+                },
+            },
+            library_curate: {
+                workflowType: 'library_curate',
+                defaultLabel: 'Library Curate',
+                defaultDescription: 'Organizes saved information into a personal markdown library.',
+                buildDefaultWorkflowConfig: () => ({ categories: [] }),
+                buildPrompt: ({ definition, instance, snapshot }) => {
+                    const categories = this.getCuratorCategories(instance.workflowConfig);
+                    const template = definition.promptTemplateOverride?.trim()
+                        || getPlatformWorkflowCatalogEntry('library_curate').defaultPromptTemplate;
+                    return [
+                        '# Platform library curate workflow run',
+                        '',
+                        `Definition: ${definition.label} (${definition.definitionId})`,
+                        '',
+                        template,
+                        '',
+                        'Return only a JSON object. Do not include markdown, comments, or prose outside the JSON.',
+                        'Schema:',
+                        '{',
+                        '  "operations": [',
+                        '    {',
+                        '      "kind": "create | update",',
+                        '      "relativePath": "category/topic/file.md",',
+                        '      "title": "document title",',
+                        '      "summary": "short summary",',
+                        '      "content": "# Markdown content",',
+                        '      "sourceSavedItemIds": ["saved-item-id"]',
+                        '    }',
+                        '  ],',
+                        '  "processedSavedItemIds": ["saved-item-id"]',
+                        '}',
+                        '',
+                        'Rules:',
+                        '- Only create or update markdown documents under the personal library.',
+                        '- Prefer updating an existing document before creating a new one.',
+                        '- Do not rename, move, or delete documents.',
+                        '- Do not target reserved/system paths such as `.meta/*` or `INDEX.md`.',
+                        '- Every processedSavedItemId must come from the provided inbox items.',
+                        '',
+                        '```json',
+                        JSON.stringify({
+                            workflowConfig: { categories },
+                            resources: snapshot,
+                        }, null, 2),
+                        '```',
+                    ].join('\n');
+                },
+                shouldSkip: async ({ snapshot }) => {
+                    const savedItems = Array.isArray(snapshot.savedInboxItems) ? snapshot.savedInboxItems : [];
+                    if (savedItems.length === 0)
+                        return { skipped: true, reason: 'No inbox items to organize' };
+                    return null;
+                },
+                finalize: async ({ userId, runId, rawOutputText, snapshot }) => {
+                    const plan = parseCuratorPlan(rawOutputText);
+                    const savedItems = Array.isArray(snapshot.savedInboxItems) ? snapshot.savedInboxItems : [];
+                    const result = await this.libraryService.applyStructuredCuratorPlan({
+                        userId,
+                        runId,
+                        plan,
+                        savedItems,
+                    });
+                    return {
+                        outputJson: plan,
+                        resultJson: result,
+                        generatedCount: result.writtenDocuments,
+                    };
+                },
+            },
+        };
+    }
+    async ensureBuiltinPlatformAgentsForUser(params) {
+        await this.suggestedPlannerService.ensureConfigForUser(params);
+        await this.libraryService.ensureConfigForUser(params);
+        await this.syncBuiltinSuggestedPlannerInstance(params);
+        await this.syncBuiltinLibraryCuratorInstance(params);
+    }
+    getDefinition(definitionId) {
+        const row = this.db.prepare(`SELECT definition_id as definitionId,
+              workflow_type as workflowType,
+              label,
+              description,
+              resource_scopes_json as resourceScopesJson,
+              resource_config_json as resourceConfigJson,
+              prompt_template_override as promptTemplateOverride,
+              tool_policy_json as toolPolicyJson,
+              enabled,
+              created_at as createdAt,
+              updated_at as updatedAt
+         FROM platform_agent_definitions
+        WHERE definition_id = ?`).get(definitionId);
+        return row ? mapDefinitionRow(row) : null;
+    }
+    listDefinitions() {
+        const rows = this.db.prepare(`SELECT definition_id as definitionId,
+              workflow_type as workflowType,
+              label,
+              description,
+              resource_scopes_json as resourceScopesJson,
+              resource_config_json as resourceConfigJson,
+              prompt_template_override as promptTemplateOverride,
+              tool_policy_json as toolPolicyJson,
+              enabled,
+              created_at as createdAt,
+              updated_at as updatedAt
+         FROM platform_agent_definitions
+        ORDER BY definition_id ASC`).all();
+        return rows.map(mapDefinitionRow);
+    }
+    getWorkflowCatalog() {
+        return getPlatformWorkflowCatalog();
+    }
+    getInstance(userId, definitionId) {
+        const row = this.db.prepare(`SELECT user_id as userId,
+              definition_id as definitionId,
+              agent_id as agentId,
+              enabled,
+              schedule_interval_ms as scheduleIntervalMs,
+              workflow_config_json as workflowConfigJson,
+              runtime_config_json as runtimeConfigJson,
+              last_run_at as lastRunAt,
+              next_run_at as nextRunAt,
+              created_at as createdAt,
+              updated_at as updatedAt,
+              deleted_at as deletedAt
+         FROM platform_agent_instances
+        WHERE user_id = ? AND definition_id = ? AND deleted_at IS NULL`).get(userId, definitionId);
+        return row ? mapInstanceRow(row) : null;
+    }
+    getInstanceRow(userId, definitionId) {
+        return this.db.prepare(`SELECT user_id as userId,
+              definition_id as definitionId,
+              agent_id as agentId,
+              enabled,
+              schedule_interval_ms as scheduleIntervalMs,
+              workflow_config_json as workflowConfigJson,
+              runtime_config_json as runtimeConfigJson,
+              last_run_at as lastRunAt,
+              next_run_at as nextRunAt,
+              created_at as createdAt,
+              updated_at as updatedAt,
+              deleted_at as deletedAt
+         FROM platform_agent_instances
+        WHERE user_id = ? AND definition_id = ?`).get(userId, definitionId);
+    }
+    getLastRun(userId, definitionId) {
+        if (definitionId === 'suggested_planner') {
+            this.purgeLegacySuggestedPlannerWorkflowRuns({ userId });
+        }
+        const row = this.db.prepare(`SELECT run_id as runId,
+              user_id as userId,
+              definition_id as definitionId,
+              mode,
+              status,
+              created_at as createdAt,
+              completed_at as completedAt,
+              error,
+              generated_count as generatedCount,
+              resources_accessed_json as resourcesAccessedJson
+         FROM platform_agent_runs
+        WHERE user_id = ? AND definition_id = ?
+        ORDER BY created_at DESC
+        LIMIT 1`).get(userId, definitionId);
+        return row ? mapRunRow(row) : null;
+    }
+    getPlatformRunContextForAgent(agentId) {
+        const row = this.db.prepare(`SELECT pai.definition_id as definitionId,
+              pad.workflow_type as workflowType
+         FROM platform_agent_instances pai
+         JOIN platform_agent_definitions pad ON pad.definition_id = pai.definition_id
+        WHERE pai.agent_id = ?
+        LIMIT 1`).get(agentId);
+        return row ?? null;
+    }
+    async listPlatformAgentsForUser(params) {
+        this.purgeLegacySuggestedPlannerWorkflowRuns({ userId: params.userId });
+        await this.ensureBuiltinPlatformAgentsForUser(params);
+        for (const definition of this.listDefinitions()) {
+            const row = this.getInstanceRow(params.userId, definition.definitionId);
+            if (row?.deletedAt)
+                continue; // skip deleted instances; do not auto-recreate
+            await this.ensureInstanceForUser({ ...params, definitionId: definition.definitionId });
+        }
+        const result = [];
+        for (const definition of this.listDefinitions()) {
+            const instance = this.getInstance(params.userId, definition.definitionId);
+            if (!instance)
+                continue;
+            result.push({
+                definition,
+                instance,
+                agent: this.conversationManager.getAgent(instance.agentId),
+                lastRun: this.getLastRun(params.userId, definition.definitionId),
+            });
+        }
+        return result;
+    }
+    async createDefinition(params) {
+        const definitionId = sanitizeDefinitionId(params.definitionId);
+        if (this.getDefinition(definitionId)) {
+            throw new Error(`Platform definition "${definitionId}" already exists.`);
+        }
+        const now = Date.now();
+        const toolPolicy = normalizePlatformAgentToolPolicy(params.workflowType, params.toolPolicy);
+        const resourceScopes = normalizePlatformResourceScopes(params.workflowType, params.resourceScopes);
+        this.db.prepare(`INSERT INTO platform_agent_definitions(
+         definition_id, workflow_type, label, description, resource_scopes_json,
+         resource_config_json, prompt_template_override, tool_policy_json,
+         enabled, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(definitionId, params.workflowType, params.label.trim(), params.description.trim(), JSON.stringify(resourceScopes), JSON.stringify(params.resourceConfig ?? {}), params.promptTemplateOverride?.trim() || null, JSON.stringify(toolPolicy), params.enabled === false ? 0 : 1, now, now);
+        const users = this.db.prepare(`SELECT id as userId, username FROM users`).all();
+        for (const user of users) {
+            await this.ensureInstanceForUser({ userId: user.userId, username: user.username, definitionId });
+        }
+        return this.getDefinition(definitionId);
+    }
+    async updateDefinition(definitionId, patch) {
+        const existing = this.getDefinition(definitionId);
+        if (!existing)
+            throw new Error('Platform definition not found.');
+        const now = Date.now();
+        const nextWorkflowType = existing.workflowType;
+        const nextLabel = patch.label?.trim() || existing.label;
+        const nextDescription = patch.description?.trim() || existing.description;
+        const nextResourceScopes = patch.resourceScopes
+            ? normalizePlatformResourceScopes(nextWorkflowType, patch.resourceScopes)
+            : existing.resourceScopes;
+        const nextResourceConfig = Object.prototype.hasOwnProperty.call(patch, 'resourceConfig')
+            ? (patch.resourceConfig ?? {})
+            : (existing.resourceConfig ?? {});
+        const nextPromptTemplate = Object.prototype.hasOwnProperty.call(patch, 'promptTemplateOverride')
+            ? patch.promptTemplateOverride?.trim() || null
+            : existing.promptTemplateOverride ?? null;
+        const nextToolPolicy = patch.toolPolicy
+            ? normalizePlatformAgentToolPolicy(nextWorkflowType, patch.toolPolicy)
+            : normalizePlatformAgentToolPolicy(nextWorkflowType, existing.toolPolicy);
+        const nextEnabled = patch.enabled ?? existing.enabled;
+        this.db.prepare(`UPDATE platform_agent_definitions
+          SET label = ?,
+              description = ?,
+              resource_scopes_json = ?,
+              resource_config_json = ?,
+              prompt_template_override = ?,
+              tool_policy_json = ?,
+              enabled = ?,
+              updated_at = ?
+        WHERE definition_id = ?`).run(nextLabel, nextDescription, JSON.stringify(nextResourceScopes), JSON.stringify(nextResourceConfig), nextPromptTemplate, JSON.stringify(nextToolPolicy), nextEnabled ? 1 : 0, now, definitionId);
+        if (nextEnabled && !existing.enabled) {
+            const users = this.db.prepare(`SELECT id as userId, username FROM users`).all();
+            for (const user of users) {
+                const row = this.getInstanceRow(user.userId, definitionId);
+                if (row?.deletedAt)
+                    continue; // do not auto-recreate deleted instances
+                await this.ensureInstanceForUser({ userId: user.userId, username: user.username, definitionId });
+            }
+        }
+        await this.syncInstancesForDefinition(definitionId);
+        if (!nextEnabled && existing.enabled) {
+            await this.cleanupPlatformAgentDefinitionRuntime({
+                definitionId,
+                reason: 'Platform agent definition disabled.',
+            });
+        }
+        return this.getDefinition(definitionId);
+    }
+    async ensureInstanceForUser(params) {
+        const existingRow = this.getInstanceRow(params.userId, params.definitionId);
+        if (existingRow?.deletedAt) {
+            throw new Error('Platform agent instance has been deleted.');
+        }
+        if (params.definitionId === 'suggested_planner') {
+            return this.syncBuiltinSuggestedPlannerInstance(params);
+        }
+        if (params.definitionId === 'library_curator') {
+            return this.syncBuiltinLibraryCuratorInstance(params);
+        }
+        const definition = this.getDefinition(params.definitionId);
+        if (!definition)
+            throw new Error('Platform definition not found.');
+        const existing = this.getInstance(params.userId, params.definitionId);
+        if (existing) {
+            return this.syncExistingCustomInstance({ ...params, definition, existing });
+        }
+        const now = Date.now();
+        const workspacePath = this.buildCustomWorkspacePath(definition, params.username);
+        fs.mkdirSync(workspacePath, { recursive: true });
+        const runtimeConfig = this.buildDefaultRuntimeConfig(definition.workflowType);
+        const nodeId = this.pickNodeId(definition.workflowType);
+        const toolPolicy = normalizePlatformAgentToolPolicy(definition.workflowType, definition.toolPolicy);
+        const agentId = randomUUID();
+        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(?, ?, ?, 'platform_agent', ?, ?, ?, ?, ?, ?, '', ?, '', ?, ?, ?, ?, NULL, NULL, ?, ?)`).run(agentId, definition.label, PLATFORM_AGENT_TYPE, runtimeConfig.model ?? 'deepseek-v4-pro', runtimeConfig.reasoningEffort ?? null, 'bypassPermissions', null, null, 'default', definition.description, Object.keys(runtimeConfig.envVars ?? {}).length > 0 ? JSON.stringify(runtimeConfig.envVars) : null, JSON.stringify(toolPolicy.disabledToolKinds ?? []), nodeId, workspacePath, now, now);
+        this.db.prepare(`INSERT OR IGNORE INTO agent_channel_memberships(agent_id, channel_id, is_home, joined_at)
+       VALUES(?, 'default', 1, ?)`).run(agentId, now);
+        this.db.prepare(`INSERT OR IGNORE INTO user_agent_access(user_id, agent_id, granted_at) VALUES(?, ?, ?)`).run(params.userId, agentId, now);
+        const instance = this.upsertInstance({
+            userId: params.userId,
+            definitionId: params.definitionId,
+            agentId,
+            enabled: definition.enabled,
+            scheduleIntervalMs: DEFAULT_PLATFORM_AGENT_INTERVAL_MS,
+            workflowConfig: this.workflowHandlers[definition.workflowType].buildDefaultWorkflowConfig(),
+            runtimeConfig,
+            lastRunAt: null,
+            nextRunAt: now + DEFAULT_PLATFORM_AGENT_INTERVAL_MS,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return instance;
+    }
+    async openConversation(userId, username, definitionId, mode) {
+        const definition = this.getDefinition(definitionId);
+        if (!definition?.enabled)
+            return null;
+        const instance = await this.ensureInstanceForUser({ userId, username, definitionId });
+        if (!instance.enabled)
+            return null;
+        const title = getPlatformAgentConversationTitle({ definitionId, mode });
+        return this.conversationManager.openNamedAgentPrimaryThread?.({
+            agentId: instance.agentId,
+            title,
+            userId,
+            legacyTitles: mode === 'debug' ? getPlatformAgentLegacyConversationTitles(definitionId) : undefined,
+        }) ?? this.conversationManager.openAgentThread(instance.agentId, userId);
+    }
+    async updateInstance(params) {
+        const definition = this.getDefinition(params.definitionId);
+        if (!definition)
+            throw new Error('Platform definition not found.');
+        let instance = await this.ensureInstanceForUser(params);
+        if (isBuiltinPlatformAgentDefinitionId(params.definitionId)) {
+            instance = await this.updateBuiltinInstance({
+                ...params,
+                definitionId: params.definitionId,
+            }, definition);
+        }
+        else {
+            instance = this.updateCustomInstance({
+                definition,
+                instance,
+                enabled: params.enabled,
+                scheduleIntervalMs: params.scheduleIntervalMs,
+                workflowConfig: params.workflowConfig,
+                runtimeConfig: params.runtimeConfig,
+            });
+        }
+        if (params.enabled === false) {
+            await this.cleanupPlatformAgentInstanceRuntime({
+                userId: params.userId,
+                definitionId: params.definitionId,
+                agentId: instance.agentId,
+                reason: 'Platform agent instance disabled.',
+            });
+        }
+        return {
+            definition,
+            instance,
+            agent: this.conversationManager.getAgent(instance.agentId),
+            lastRun: this.getLastRun(params.userId, params.definitionId),
+        };
+    }
+    deleteInstance(userId, definitionId) {
+        const definition = this.getDefinition(definitionId);
+        if (!definition)
+            return { ok: false, error: 'Platform definition not found' };
+        const existing = this.getInstanceRow(userId, definitionId);
+        if (!existing || existing.deletedAt) {
+            return { ok: false, error: 'Platform agent instance not found or already deleted' };
+        }
+        const now = Date.now();
+        const result = this.db.prepare(`UPDATE platform_agent_instances
+          SET deleted_at = ?,
+              enabled = 0,
+              next_run_at = NULL,
+              updated_at = ?
+        WHERE user_id = ? AND definition_id = ? AND deleted_at IS NULL`).run(now, now, userId, definitionId);
+        if (result.changes === 0) {
+            return { ok: false, error: 'Platform agent instance not found or already deleted' };
+        }
+        this.syncBuiltinLegacyMirrorFromRow({
+            ...existing,
+            enabled: 0,
+            nextRunAt: null,
+            updatedAt: now,
+            deletedAt: now,
+        });
+        void this.cleanupPlatformAgentInstanceRuntime({
+            userId,
+            definitionId,
+            agentId: existing.agentId,
+            reason: 'Platform agent instance deleted.',
+        });
+        return { ok: true };
+    }
+    async cleanupPlatformAgentInstanceRuntime(params) {
+        const targets = this.db.prepare(`SELECT id as conversationId,
+              node_id as nodeId,
+              agent_type as agentType,
+              session_key as sessionKey
+         FROM conversations
+        WHERE agent_id = ?`).all(params.agentId);
+        const uniqueTargets = new Map();
+        for (const target of targets) {
+            const hostKey = `conversation:${target.conversationId}:${target.agentType}`;
+            uniqueTargets.set(hostKey, {
+                conversationId: target.conversationId,
+                nodeId: target.nodeId,
+                hostKey,
+                sessionKey: target.sessionKey,
+            });
+        }
+        const now = Date.now();
+        this.db.transaction(() => {
+            for (const target of uniqueTargets.values()) {
+                this.db.prepare(`DELETE FROM node_dispatch_queue
+            WHERE host_key = ?
+               OR session_key = ?
+               OR conversation_id = ?`).run(target.hostKey, target.sessionKey, target.conversationId);
+                this.db.prepare(`DELETE FROM node_host_snapshots
+            WHERE host_key = ?
+               OR session_key = ?`).run(target.hostKey, target.sessionKey);
+                this.db.prepare(`DELETE FROM conversation_prompt_queue WHERE conversation_id = ?`).run(target.conversationId);
+                this.db.prepare(`UPDATE conversations
+              SET status = CASE
+                    WHEN status IN ('queued', 'active', 'recovering', 'awaiting_approval') THEN 'idle'
+                    ELSE status
+                  END
+            WHERE id = ?`).run(target.conversationId);
+                this.db.prepare(`UPDATE runs
+              SET ended_at = COALESCE(ended_at, ?),
+                  stop_reason = COALESCE(stop_reason, 'error'),
+                  error = COALESCE(error, ?)
+            WHERE session_key = ?
+              AND ended_at IS NULL`).run(now, params.reason, target.sessionKey);
+            }
+            this.db.prepare(`UPDATE platform_agent_runs
+            SET status = 'failed',
+                completed_at = COALESCE(completed_at, ?),
+                error = COALESCE(error, ?)
+          WHERE user_id = ?
+            AND definition_id = ?
+            AND status = 'running'`).run(now, params.reason, params.userId, params.definitionId);
+        })();
+        if (!this.agentRuntimeCleanupBroker)
+            return;
+        const targetsByNode = new Map();
+        for (const target of uniqueTargets.values()) {
+            if (!target.nodeId)
+                continue;
+            const entry = targetsByNode.get(target.nodeId) ?? { hostKeys: new Set(), sessionKeys: new Set() };
+            entry.hostKeys.add(target.hostKey);
+            entry.sessionKeys.add(target.sessionKey);
+            targetsByNode.set(target.nodeId, entry);
+        }
+        for (const [nodeId, target] of targetsByNode.entries()) {
+            try {
+                await this.agentRuntimeCleanupBroker.cleanupAgentRuntime({
+                    nodeId,
+                    agentId: params.agentId,
+                    hostKeys: [...target.hostKeys],
+                    sessionKeys: [...target.sessionKeys],
+                });
+            }
+            catch (error) {
+                log.warn('[platform-agent] runtime cleanup failed; stale node state will be rejected on reconnect', {
+                    userId: params.userId,
+                    definitionId: params.definitionId,
+                    agentId: params.agentId,
+                    nodeId,
+                    error: String(error?.message ?? error),
+                });
+            }
+        }
+    }
+    async cleanupPlatformAgentDefinitionRuntime(params) {
+        const rows = this.db.prepare(`SELECT user_id as userId,
+              definition_id as definitionId,
+              agent_id as agentId,
+              enabled,
+              schedule_interval_ms as scheduleIntervalMs,
+              workflow_config_json as workflowConfigJson,
+              runtime_config_json as runtimeConfigJson,
+              last_run_at as lastRunAt,
+              next_run_at as nextRunAt,
+              created_at as createdAt,
+              updated_at as updatedAt,
+              deleted_at as deletedAt
+         FROM platform_agent_instances
+        WHERE definition_id = ?
+          AND deleted_at IS NULL`).all(params.definitionId);
+        for (const row of rows) {
+            await this.cleanupPlatformAgentInstanceRuntime({
+                userId: row.userId,
+                definitionId: row.definitionId,
+                agentId: row.agentId,
+                reason: params.reason,
+            });
+        }
+    }
+    syncBuiltinLegacyMirrorFromRow(row) {
+        this.syncBuiltinLegacyMirror(mapInstanceRow(row));
+    }
+    syncBuiltinLegacyMirror(instance) {
+        if (instance.definitionId === 'suggested_planner') {
+            this.syncSuggestedPlannerLegacyMirror(instance);
+            return;
+        }
+        if (instance.definitionId === 'library_curator') {
+            this.syncLibraryCuratorLegacyMirror(instance);
+        }
+    }
+    syncSuggestedPlannerLegacyMirror(instance) {
+        try {
+            const now = Date.now();
+            this.db.prepare(`UPDATE suggested_planner_configs
+            SET enabled = ?,
+                schedule_interval_ms = ?,
+                lookback_days = ?,
+                last_run_at = ?,
+                next_run_at = ?,
+                updated_at = ?
+          WHERE user_id = ?`).run(instance.enabled ? 1 : 0, Math.max(60_000, instance.scheduleIntervalMs), this.getPlannerLookbackDays(instance.workflowConfig), instance.lastRunAt, instance.enabled ? instance.nextRunAt : null, now, instance.userId);
+        }
+        catch {
+            // Legacy mirror may be absent in narrow tests or future schemas.
+        }
+    }
+    syncLibraryCuratorLegacyMirror(instance) {
+        try {
+            const now = Date.now();
+            this.db.prepare(`UPDATE library_curator_configs
+            SET enabled = ?,
+                schedule_interval_ms = ?,
+                categories_json = ?,
+                last_run_at = ?,
+                next_run_at = ?,
+                updated_at = ?
+          WHERE user_id = ?`).run(instance.enabled ? 1 : 0, Math.max(60_000, instance.scheduleIntervalMs), JSON.stringify(this.getCuratorCategories(instance.workflowConfig)), instance.lastRunAt, instance.enabled ? instance.nextRunAt : null, now, instance.userId);
+        }
+        catch {
+            // Legacy mirror may be absent in narrow tests or future schemas.
+        }
+    }
+    restoreInstance(userId, definitionId) {
+        const definition = this.getDefinition(definitionId);
+        if (!definition)
+            throw new Error('Platform definition not found.');
+        const now = Date.now();
+        const row = this.getInstanceRow(userId, definitionId);
+        if (!row || !row.deletedAt) {
+            throw new Error('Platform agent instance not found or not deleted');
+        }
+        const scheduleIntervalMs = row.scheduleIntervalMs ?? DEFAULT_PLATFORM_AGENT_INTERVAL_MS;
+        const result = this.db.prepare(`UPDATE platform_agent_instances
+          SET deleted_at = NULL,
+              enabled = 1,
+              next_run_at = ?,
+              updated_at = ?
+        WHERE user_id = ? AND definition_id = ? AND deleted_at IS NOT NULL`).run(now + scheduleIntervalMs, now, userId, definitionId);
+        if (result.changes === 0) {
+            throw new Error('Platform agent instance not found or not deleted');
+        }
+        const restored = this.getInstance(userId, definitionId);
+        if (!restored) {
+            throw new Error('Platform agent instance restore failed');
+        }
+        this.syncBuiltinLegacyMirror(restored);
+        return restored;
+    }
+    async dispatchWorkflowRun(params) {
+        if (params.definitionId === 'suggested_planner') {
+            this.purgeLegacySuggestedPlannerWorkflowRuns({ userId: params.userId });
+        }
+        const definition = this.getDefinition(params.definitionId);
+        if (!definition)
+            return { ok: false, error: 'Platform definition not found' };
+        const instance = await this.ensureInstanceForUser(params);
+        if (!definition.enabled) {
+            return { ok: true, skipped: true, reason: 'Platform definition is disabled' };
+        }
+        if (!instance.enabled) {
+            return { ok: true, skipped: true, reason: 'Platform instance is disabled' };
+        }
+        this.reconcileTerminalPlatformRunRuntimeState(params.userId, params.definitionId);
+        await this.reconcileCompletedRunningRuns(params.userId, params.definitionId);
+        const running = this.db.prepare(`SELECT run_id as runId
+         FROM platform_agent_runs
+        WHERE user_id = ? AND definition_id = ? AND status = 'running'
+        ORDER BY created_at DESC
+        LIMIT 1`).get(params.userId, params.definitionId);
+        if (running) {
+            return { ok: true, skipped: true, queued: true, runId: running.runId, reason: 'Platform agent run already in progress' };
+        }
+        const handler = this.workflowHandlers[definition.workflowType];
+        const snapshot = await this.buildResourceSnapshot({
+            userId: params.userId,
+            username: params.username,
+            definition,
+            instance,
+        });
+        const dispatchInput = {
+            definition,
+            instance,
+            userId: params.userId,
+            username: params.username,
+            snapshot,
+        };
+        const skip = await handler.shouldSkip?.(dispatchInput);
+        if (skip) {
+            this.scheduleNextRun(params.userId, params.definitionId, Date.now(), instance.scheduleIntervalMs);
+            return { ok: true, skipped: true, reason: skip.reason };
+        }
+        const conversation = await this.openConversation(params.userId, params.username, params.definitionId, 'workflow');
+        if (!conversation)
+            return { ok: false, error: 'Failed to open platform workflow conversation' };
+        const prompt = handler.buildPrompt(dispatchInput);
+        const activationMetadata = {
+            platformRun: {
+                definitionId: definition.definitionId,
+                workflowType: definition.workflowType,
+                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, params.definitionId, now, instance.scheduleIntervalMs);
+            return { ok: false, error: 'Failed to start platform agent run', queued: result.queued };
+        }
+        const existingRun = this.db.prepare(`SELECT status
+         FROM platform_agent_runs
+        WHERE run_id = ?`).get(result.runId);
+        if (existingRun) {
+            this.reconcileTerminalPlatformRunRuntimeState(params.userId, params.definitionId);
+            return {
+                ok: true,
+                skipped: true,
+                queued: true,
+                runId: result.runId,
+                reason: existingRun.status === 'running'
+                    ? 'Platform agent run already in progress'
+                    : 'Platform agent runtime returned an already recorded run',
+            };
+        }
+        const resourcesAccessed = {
+            savedItems: Array.isArray(snapshot.savedInboxItems) ? snapshot.savedInboxItems.length : 0,
+            tasks: Array.isArray(snapshot.openTasks) ? snapshot.openTasks.length : 0,
+            messages: Array.isArray(snapshot.recentMessages) ? snapshot.recentMessages.length : 0,
+        };
+        this.db.prepare(`INSERT INTO platform_agent_runs(
+         run_id, user_id, definition_id, agent_id, mode, status, created_at,
+         input_snapshot_json, generated_count, resources_accessed_json
+       ) VALUES(?, ?, ?, ?, 'workflow', 'running', ?, ?, 0, ?)`).run(result.runId, params.userId, definition.definitionId, instance.agentId, now, JSON.stringify(snapshot), JSON.stringify(resourcesAccessed));
+        this.db.prepare(`UPDATE platform_agent_instances
+          SET last_run_at = ?,
+              updated_at = ?
+        WHERE user_id = ? AND definition_id = ?`).run(now, now, params.userId, definition.definitionId);
+        await this.reconcileRunStateAfterInsert({
+            runId: result.runId,
+            definitionId: definition.definitionId,
+        });
+        return { ok: true, runId: result.runId, queued: result.queued, generatedCount: 0 };
+    }
+    async finalizeRun(params) {
+        const row = this.db.prepare(`SELECT run_id as runId,
+              user_id as userId,
+              definition_id as definitionId,
+              mode,
+              status,
+              created_at as createdAt,
+              completed_at as completedAt,
+              error,
+              generated_count as generatedCount,
+              resources_accessed_json as resourcesAccessedJson
+         FROM platform_agent_runs
+        WHERE run_id = ?`).get(params.runId);
+        if (!row || row.status !== 'running')
+            return;
+        const definition = this.getDefinition(row.definitionId);
+        const instance = definition ? this.getInstance(row.userId, row.definitionId) : null;
+        if (!definition || !instance)
+            return;
+        const now = Date.now();
+        const persistedError = params.error?.trim() || null;
+        if (persistedError) {
+            this.db.prepare(`UPDATE platform_agent_runs
+            SET status = 'failed',
+                completed_at = ?,
+                error = ?
+          WHERE run_id = ?`).run(now, persistedError, params.runId);
+            this.scheduleNextRun(row.userId, row.definitionId, now, instance.scheduleIntervalMs);
+            return;
+        }
+        try {
+            const rawOutputText = this.getRunOutputText(params.runId);
+            const snapshotRow = this.db.prepare(`SELECT input_snapshot_json as inputSnapshotJson
+           FROM platform_agent_runs
+          WHERE run_id = ?`).get(params.runId);
+            if (definition.definitionId === 'library_curator' && !snapshotRow?.inputSnapshotJson?.trim()) {
+                const legacy = await this.finalizeLegacyCuratorRun(params.runId, row.userId, now);
+                this.db.prepare(`UPDATE platform_agent_runs
+              SET status = ?,
+                  completed_at = ?,
+                  raw_output_text = ?,
+                  error = ?,
+                  generated_count = ?
+            WHERE run_id = ?`).run(legacy.status, legacy.completedAt, rawOutputText || null, legacy.error, legacy.generatedCount, params.runId);
+                this.scheduleNextRun(row.userId, row.definitionId, now, instance.scheduleIntervalMs);
+                return;
+            }
+            const handler = this.workflowHandlers[definition.workflowType];
+            const result = await handler.finalize({
+                definition,
+                instance,
+                userId: row.userId,
+                username: this.getUsernameForUserId(row.userId) ?? 'user',
+                runId: params.runId,
+                rawOutputText,
+                snapshot: parseJsonRecord(snapshotRow?.inputSnapshotJson),
+            });
+            this.db.prepare(`UPDATE platform_agent_runs
+            SET status = 'completed',
+                completed_at = ?,
+                raw_output_text = ?,
+                output_json = ?,
+                result_json = ?,
+                generated_count = ?
+          WHERE run_id = ?`).run(now, rawOutputText || null, result.outputJson ? JSON.stringify(result.outputJson) : null, result.resultJson ? JSON.stringify(result.resultJson) : null, result.generatedCount ?? 0, params.runId);
+        }
+        catch (error) {
+            this.db.prepare(`UPDATE platform_agent_runs
+            SET status = 'failed',
+                completed_at = ?,
+                raw_output_text = ?,
+                error = ?
+          WHERE run_id = ?`).run(now, this.getRunOutputText(params.runId) || null, String(error?.message ?? error), params.runId);
+        }
+        this.scheduleNextRun(row.userId, row.definitionId, now, instance.scheduleIntervalMs);
+    }
+    listDueInstances(now) {
+        const rows = this.db.prepare(`SELECT pai.user_id as userId,
+              pai.definition_id as definitionId,
+              pai.agent_id as agentId,
+              pai.enabled,
+              pai.schedule_interval_ms as scheduleIntervalMs,
+              pai.workflow_config_json as workflowConfigJson,
+              pai.runtime_config_json as runtimeConfigJson,
+              pai.last_run_at as lastRunAt,
+              pai.next_run_at as nextRunAt,
+              pai.created_at as createdAt,
+              pai.updated_at as updatedAt,
+              pai.deleted_at as deletedAt
+         FROM platform_agent_instances pai
+         JOIN platform_agent_definitions pad ON pad.definition_id = pai.definition_id
+        WHERE pai.enabled = 1
+          AND pad.enabled = 1
+          AND pai.next_run_at IS NOT NULL
+          AND pai.next_run_at <= ?
+          AND pai.deleted_at IS NULL`).all(now);
+        return rows.map(mapInstanceRow);
+    }
+    purgeLegacySuggestedPlannerWorkflowRuns(params) {
+        const filters = [
+            `r.ended_at IS NULL`,
+            `r.prompt_text LIKE ?`,
+            `(spr.run_id IS NOT NULL OR (par.run_id IS NOT NULL AND par.definition_id = 'suggested_planner') OR c.title = ?)`,
+        ];
+        const args = [
+            `${LEGACY_SUGGESTED_PLANNER_PROMPT_PREFIX}%`,
+            getPlatformAgentConversationTitle({ definitionId: 'suggested_planner', mode: 'workflow' }),
+        ];
+        if (params?.userId) {
+            filters.push(`COALESCE(spr.user_id, par.user_id, c.user_id) = ?`);
+            args.push(params.userId);
+        }
+        if (params?.runIds?.length) {
+            filters.push(`r.run_id IN (${params.runIds.map(() => '?').join(', ')})`);
+            args.push(...params.runIds);
+        }
+        const rows = this.db.prepare(`SELECT r.run_id as runId,
+              COALESCE(spr.user_id, par.user_id, c.user_id) as userId,
+              r.session_key as sessionKey,
+              c.id as conversationId,
+              c.agent_type as agentType,
+              c.node_id as nodeId,
+              h.current_run_id as snapshotRunId,
+              h.host_key as hostKey,
+              COALESCE(spc.schedule_interval_ms, pai.schedule_interval_ms, ?) as scheduleIntervalMs
+         FROM runs r
+         LEFT JOIN suggested_planner_runs spr ON spr.run_id = r.run_id
+         LEFT JOIN platform_agent_runs par ON par.run_id = r.run_id
+         LEFT JOIN conversations c ON c.session_key = r.session_key
+         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 = r.run_id
+         LEFT JOIN suggested_planner_configs spc ON spc.user_id = COALESCE(spr.user_id, par.user_id, c.user_id)
+         LEFT JOIN platform_agent_instances pai
+           ON pai.user_id = COALESCE(spr.user_id, par.user_id, c.user_id)
+          AND pai.definition_id = 'suggested_planner'
+        WHERE ${filters.join(' AND ')}
+        ORDER BY r.started_at ASC`).all(DEFAULT_PLATFORM_AGENT_INTERVAL_MS, ...args);
+        if (rows.length === 0)
+            return [];
+        for (const row of rows) {
+            if (!row.conversationId)
+                continue;
+            this.conversationManager.cancelConversationRun(row.conversationId, row.runId, {
+                strictExpectedRunId: true,
+            });
+        }
+        const now = Date.now();
+        const transaction = this.db.transaction(() => {
+            for (const row of rows) {
+                const nextRunAt = now + Math.max(5_000, row.scheduleIntervalMs ?? DEFAULT_PLATFORM_AGENT_INTERVAL_MS);
+                this.db.prepare(`UPDATE runs
+              SET ended_at = COALESCE(ended_at, ?),
+                  stop_reason = COALESCE(stop_reason, 'error'),
+                  error = COALESCE(error, ?)
+            WHERE run_id = ?
+              AND ended_at IS NULL`).run(now, LEGACY_SUGGESTED_PLANNER_CLEANUP_ERROR, row.runId);
+                this.db.prepare(`UPDATE platform_agent_runs
+              SET status = 'failed',
+                  completed_at = COALESCE(completed_at, ?),
+                  error = COALESCE(error, ?)
+            WHERE run_id = ?
+              AND status = 'running'`).run(now, LEGACY_SUGGESTED_PLANNER_CLEANUP_ERROR, row.runId);
+                this.db.prepare(`UPDATE suggested_planner_runs
+              SET status = 'failed',
+                  completed_at = COALESCE(completed_at, ?),
+                  error = COALESCE(error, ?)
+            WHERE run_id = ?
+              AND status = 'running'`).run(now, LEGACY_SUGGESTED_PLANNER_CLEANUP_ERROR, row.runId);
+                if (row.userId) {
+                    this.db.prepare(`UPDATE suggested_planner_configs
+                SET next_run_at = ?,
+                    updated_at = ?
+              WHERE user_id = ?`).run(nextRunAt, now, row.userId);
+                    this.db.prepare(`UPDATE platform_agent_instances
+                SET next_run_at = ?,
+                    updated_at = ?
+              WHERE user_id = ?
+                AND definition_id = 'suggested_planner'`).run(nextRunAt, now, row.userId);
+                }
+                this.db.prepare(`DELETE FROM node_dispatch_queue WHERE run_id = ?`).run(row.runId);
+                if (row.conversationId) {
+                    this.db.prepare(`DELETE FROM conversation_prompt_queue WHERE conversation_id = ?`).run(row.conversationId);
+                    this.db.prepare(`UPDATE conversations
+                SET status = 'idle',
+                    updated_at = ?
+              WHERE id = ?
+                AND status IN ('queued', 'active', 'recovering', 'awaiting_approval')`).run(now, row.conversationId);
+                }
+                if (row.nodeId && row.hostKey) {
+                    this.db.prepare(`DELETE FROM node_host_snapshots
+              WHERE node_id = ?
+                AND host_key = ?
+                AND current_run_id = ?`).run(row.nodeId, row.hostKey, row.runId);
+                }
+            }
+        });
+        transaction();
+        return rows.map((row) => row.runId);
+    }
+    getUsernameForUserId(userId) {
+        const row = this.db.prepare(`SELECT username FROM users WHERE id = ?`).get(userId);
+        return row?.username?.trim() || null;
+    }
+    async syncBuiltinSuggestedPlannerInstance(params, override) {
+        const config = await this.suggestedPlannerService.ensureConfigForUser(params);
+        const definition = this.getDefinition('suggested_planner') ?? getBuiltinPlatformDefinition({ definitionId: 'suggested_planner' });
+        const agent = this.suggestedPlannerService.getPlannerAgent(params.userId);
+        const existing = this.getInstance(params.userId, 'suggested_planner');
+        const defaultRuntimeConfig = {
+            model: agent?.model ?? null,
+            reasoningEffort: agent?.reasoningEffort ?? null,
+            envVars: agent?.envVars ?? {},
+        };
+        if (agent?.agentRole !== 'platform_agent') {
+            this.db.prepare(`UPDATE agents
+            SET agent_role = 'platform_agent',
+                description = ?,
+                disabled_tool_kinds = ?,
+                updated_at = ?
+          WHERE agent_id = ?`).run(definition.description, JSON.stringify(normalizePlatformAgentToolPolicy(definition.workflowType, definition.toolPolicy).disabledToolKinds ?? []), Date.now(), config.plannerAgentId);
+        }
+        const workflowConfig = override?.workflowConfig
+            ?? existing?.workflowConfig
+            ?? { lookbackDays: config.lookbackDays };
+        const runtimeConfig = override?.runtimeConfig
+            ?? existing?.runtimeConfig
+            ?? defaultRuntimeConfig;
+        const instance = this.upsertInstance({
+            userId: params.userId,
+            definitionId: 'suggested_planner',
+            agentId: config.plannerAgentId,
+            enabled: override?.enabled ?? existing?.enabled ?? config.enabled,
+            scheduleIntervalMs: override?.scheduleIntervalMs ?? existing?.scheduleIntervalMs ?? config.scheduleIntervalMs,
+            workflowConfig,
+            runtimeConfig,
+            lastRunAt: override && Object.prototype.hasOwnProperty.call(override, 'lastRunAt')
+                ? override.lastRunAt ?? null
+                : existing
+                    ? existing.lastRunAt
+                    : config.lastRunAt,
+            nextRunAt: override && Object.prototype.hasOwnProperty.call(override, 'nextRunAt')
+                ? override.nextRunAt ?? null
+                : existing
+                    ? existing.nextRunAt
+                    : config.nextRunAt,
+            createdAt: config.createdAt,
+            updatedAt: Date.now(),
+        });
+        this.syncSuggestedPlannerLegacyMirror(instance);
+        return instance;
+    }
+    async syncBuiltinLibraryCuratorInstance(params, override) {
+        const config = await this.libraryService.ensureConfigForUser(params);
+        const definition = this.getDefinition('library_curator') ?? getBuiltinPlatformDefinition({ definitionId: 'library_curator' });
+        const agent = this.libraryService.getCuratorAgent(params.userId);
+        const existing = this.getInstance(params.userId, 'library_curator');
+        const defaultRuntimeConfig = {
+            model: agent?.model ?? null,
+            reasoningEffort: agent?.reasoningEffort ?? null,
+            envVars: agent?.envVars ?? {},
+        };
+        if (agent?.agentRole !== 'platform_agent') {
+            this.db.prepare(`UPDATE agents
+            SET agent_role = 'platform_agent',
+                description = ?,
+                disabled_tool_kinds = ?,
+                updated_at = ?
+          WHERE agent_id = ?`).run(definition.description, JSON.stringify(normalizePlatformAgentToolPolicy(definition.workflowType, definition.toolPolicy).disabledToolKinds ?? []), Date.now(), config.curatorAgentId);
+        }
+        const workflowConfig = override?.workflowConfig
+            ?? existing?.workflowConfig
+            ?? {
+                categories: config.categories,
+                libraryRootPath: config.libraryRootPath,
+            };
+        const runtimeConfig = override?.runtimeConfig
+            ?? existing?.runtimeConfig
+            ?? defaultRuntimeConfig;
+        const instance = this.upsertInstance({
+            userId: params.userId,
+            definitionId: 'library_curator',
+            agentId: config.curatorAgentId,
+            enabled: override?.enabled ?? existing?.enabled ?? config.enabled,
+            scheduleIntervalMs: override?.scheduleIntervalMs ?? existing?.scheduleIntervalMs ?? config.scheduleIntervalMs,
+            workflowConfig,
+            runtimeConfig,
+            lastRunAt: override && Object.prototype.hasOwnProperty.call(override, 'lastRunAt')
+                ? override.lastRunAt ?? null
+                : existing
+                    ? existing.lastRunAt
+                    : config.lastRunAt,
+            nextRunAt: override && Object.prototype.hasOwnProperty.call(override, 'nextRunAt')
+                ? override.nextRunAt ?? null
+                : existing
+                    ? existing.nextRunAt
+                    : config.nextRunAt,
+            createdAt: config.createdAt,
+            updatedAt: Date.now(),
+        });
+        this.syncLibraryCuratorLegacyMirror(instance);
+        return instance;
+    }
+    async updateBuiltinInstance(params, definition) {
+        if (params.definitionId === 'suggested_planner') {
+            const existing = await this.suggestedPlannerService.ensureConfigForUser(params);
+            const existingInstance = this.getInstance(params.userId, 'suggested_planner');
+            const workflowConfig = {
+                lookbackDays: this.getPlannerLookbackDays(params.workflowConfig ?? existingInstance?.workflowConfig ?? { lookbackDays: existing.lookbackDays }),
+            };
+            const runtimeConfig = {
+                ...(existingInstance?.runtimeConfig ?? { model: null, reasoningEffort: null, envVars: {} }),
+                ...(params.runtimeConfig ?? {}),
+                envVars: Object.prototype.hasOwnProperty.call(params.runtimeConfig ?? {}, 'envVars')
+                    ? params.runtimeConfig?.envVars ?? {}
+                    : existingInstance?.runtimeConfig.envVars ?? {},
+            };
+            const scheduleIntervalMs = Math.max(60_000, params.scheduleIntervalMs ?? existingInstance?.scheduleIntervalMs ?? existing.scheduleIntervalMs);
+            const enabled = params.enabled ?? existingInstance?.enabled ?? existing.enabled;
+            const now = Date.now();
+            const nextRunAt = enabled
+                ? existingInstance?.nextRunAt ?? existing.nextRunAt ?? now + scheduleIntervalMs
+                : null;
+            this.suggestedPlannerService.updateConfig(params.userId, {
+                enabled,
+                scheduleIntervalMs,
+                lookbackDays: this.getPlannerLookbackDays(workflowConfig),
+                model: Object.prototype.hasOwnProperty.call(params.runtimeConfig ?? {}, 'model') ? params.runtimeConfig?.model ?? null : undefined,
+                reasoningEffort: Object.prototype.hasOwnProperty.call(params.runtimeConfig ?? {}, 'reasoningEffort') ? params.runtimeConfig?.reasoningEffort ?? null : undefined,
+                envVars: Object.prototype.hasOwnProperty.call(params.runtimeConfig ?? {}, 'envVars') ? params.runtimeConfig?.envVars ?? {} : undefined,
+            });
+            return this.syncBuiltinSuggestedPlannerInstance(params, {
+                enabled,
+                scheduleIntervalMs,
+                workflowConfig,
+                runtimeConfig,
+                nextRunAt,
+                lastRunAt: existingInstance?.lastRunAt ?? existing.lastRunAt,
+            });
+        }
+        const existing = await this.libraryService.ensureConfigForUser(params);
+        const existingInstance = this.getInstance(params.userId, 'library_curator');
+        const workflowConfig = {
+            categories: this.getCuratorCategories(params.workflowConfig ?? existingInstance?.workflowConfig ?? { categories: existing.categories }),
+            libraryRootPath: typeof existingInstance?.workflowConfig.libraryRootPath === 'string'
+                ? existingInstance.workflowConfig.libraryRootPath
+                : existing.libraryRootPath,
+        };
+        const runtimeConfig = {
+            ...(existingInstance?.runtimeConfig ?? { model: null, reasoningEffort: null, envVars: {} }),
+            ...(params.runtimeConfig ?? {}),
+            envVars: Object.prototype.hasOwnProperty.call(params.runtimeConfig ?? {}, 'envVars')
+                ? params.runtimeConfig?.envVars ?? {}
+                : existingInstance?.runtimeConfig.envVars ?? {},
+        };
+        const scheduleIntervalMs = Math.max(60_000, params.scheduleIntervalMs ?? existingInstance?.scheduleIntervalMs ?? existing.scheduleIntervalMs);
+        const enabled = params.enabled ?? existingInstance?.enabled ?? existing.enabled;
+        const now = Date.now();
+        const nextRunAt = enabled
+            ? existingInstance?.nextRunAt ?? existing.nextRunAt ?? now + scheduleIntervalMs
+            : null;
+        this.libraryService.updateConfig(params.userId, {
+            enabled,
+            scheduleIntervalMs,
+            categories: workflowConfig.categories,
+        });
+        if (params.runtimeConfig) {
+            this.libraryService.updateCuratorAgentRuntime(params.userId, params.runtimeConfig);
+        }
+        return this.syncBuiltinLibraryCuratorInstance(params, {
+            enabled,
+            scheduleIntervalMs,
+            workflowConfig,
+            runtimeConfig,
+            nextRunAt,
+            lastRunAt: existingInstance?.lastRunAt ?? existing.lastRunAt,
+        });
+    }
+    updateCustomInstance(params) {
+        const now = Date.now();
+        const workflowConfig = this.sanitizeWorkflowConfig(params.definition.workflowType, params.workflowConfig ?? params.instance.workflowConfig);
+        const runtimeConfig = {
+            ...params.instance.runtimeConfig,
+            ...(params.runtimeConfig ?? {}),
+            envVars: params.runtimeConfig?.envVars ? { ...params.runtimeConfig.envVars } : (params.instance.runtimeConfig.envVars ?? {}),
+        };
+        const enabled = params.enabled ?? params.instance.enabled;
+        const scheduleIntervalMs = Math.max(60_000, params.scheduleIntervalMs ?? params.instance.scheduleIntervalMs);
+        const nextRunAt = enabled ? params.instance.nextRunAt ?? now + scheduleIntervalMs : null;
+        this.db.prepare(`UPDATE platform_agent_instances
+          SET enabled = ?,
+              schedule_interval_ms = ?,
+              workflow_config_json = ?,
+              runtime_config_json = ?,
+              next_run_at = ?,
+              updated_at = ?
+        WHERE user_id = ? AND definition_id = ?`).run(enabled ? 1 : 0, scheduleIntervalMs, JSON.stringify(workflowConfig), JSON.stringify(runtimeConfig), nextRunAt, now, params.instance.userId, params.instance.definitionId);
+        const toolPolicy = normalizePlatformAgentToolPolicy(params.definition.workflowType, params.definition.toolPolicy);
+        this.db.prepare(`UPDATE agents
+          SET name = ?,
+              description = ?,
+              model = ?,
+              reasoning_effort = ?,
+              env_vars = ?,
+              disabled_tool_kinds = ?,
+              updated_at = ?
+        WHERE agent_id = ?`).run(params.definition.label, params.definition.description, runtimeConfig.model ?? null, runtimeConfig.reasoningEffort ?? null, Object.keys(runtimeConfig.envVars ?? {}).length > 0 ? JSON.stringify(runtimeConfig.envVars) : null, JSON.stringify(toolPolicy.disabledToolKinds ?? []), now, params.instance.agentId);
+        return this.getInstance(params.instance.userId, params.instance.definitionId);
+    }
+    async syncExistingCustomInstance(params) {
+        const now = Date.now();
+        const desiredWorkspacePath = this.buildCustomWorkspacePath(params.definition, params.username);
+        fs.mkdirSync(desiredWorkspacePath, { recursive: true });
+        const runtimeConfig = {
+            ...params.existing.runtimeConfig,
+            envVars: params.existing.runtimeConfig.envVars ?? {},
+        };
+        const toolPolicy = normalizePlatformAgentToolPolicy(params.definition.workflowType, params.definition.toolPolicy);
+        const nodeId = this.pickNodeId(params.definition.workflowType);
+        this.db.prepare(`UPDATE agents
+          SET agent_role = 'platform_agent',
+              name = ?,
+              description = ?,
+              node_id = ?,
+              workspace_path = ?,
+              model = ?,
+              reasoning_effort = ?,
+              env_vars = ?,
+              disabled_tool_kinds = ?,
+              updated_at = ?
+        WHERE agent_id = ?`).run(params.definition.label, params.definition.description, nodeId, desiredWorkspacePath, runtimeConfig.model ?? null, runtimeConfig.reasoningEffort ?? null, Object.keys(runtimeConfig.envVars ?? {}).length > 0 ? JSON.stringify(runtimeConfig.envVars) : null, JSON.stringify(toolPolicy.disabledToolKinds ?? []), now, params.existing.agentId);
+        this.db.prepare(`UPDATE conversations
+          SET node_id = ?,
+              workspace_path = ?,
+              env_vars = ?,
+              updated_at = ?
+        WHERE agent_id = ?`).run(nodeId, desiredWorkspacePath, Object.keys(runtimeConfig.envVars ?? {}).length > 0 ? JSON.stringify(runtimeConfig.envVars) : null, now, params.existing.agentId);
+        return this.getInstance(params.userId, params.definition.definitionId) ?? params.existing;
+    }
+    upsertInstance(params) {
+        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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(user_id, definition_id) DO UPDATE SET
+         agent_id = excluded.agent_id,
+         enabled = excluded.enabled,
+         schedule_interval_ms = excluded.schedule_interval_ms,
+         workflow_config_json = excluded.workflow_config_json,
+         runtime_config_json = excluded.runtime_config_json,
+         last_run_at = excluded.last_run_at,
+         next_run_at = excluded.next_run_at,
+         updated_at = excluded.updated_at`).run(params.userId, params.definitionId, params.agentId, params.enabled ? 1 : 0, Math.max(60_000, params.scheduleIntervalMs), JSON.stringify(this.sanitizeWorkflowConfig(this.getDefinition(params.definitionId)?.workflowType ?? 'planner_suggestions', params.workflowConfig)), JSON.stringify({
+            model: params.runtimeConfig.model ?? null,
+            reasoningEffort: params.runtimeConfig.reasoningEffort ?? null,
+            envVars: params.runtimeConfig.envVars ?? {},
+        }), params.lastRunAt, params.nextRunAt, params.createdAt, params.updatedAt);
+        return this.getInstance(params.userId, params.definitionId);
+    }
+    async syncInstancesForDefinition(definitionId) {
+        const definition = this.getDefinition(definitionId);
+        if (!definition)
+            return;
+        if (isBuiltinPlatformAgentDefinitionId(definitionId))
+            return;
+        const rows = this.db.prepare(`SELECT user_id as userId FROM platform_agent_instances WHERE definition_id = ? AND deleted_at IS NULL`).all(definitionId);
+        for (const row of rows) {
+            const username = this.getUsernameForUserId(row.userId);
+            if (!username)
+                continue;
+            await this.ensureInstanceForUser({ userId: row.userId, username, definitionId });
+        }
+    }
+    async reconcileRunStateAfterInsert(params) {
+        const row = this.db.prepare(`SELECT r.stop_reason as stopReason,
+              r.error as error,
+              pad.workflow_type as workflowType,
+              r.ended_at as endedAt
+         FROM runs r
+         JOIN platform_agent_definitions pad ON pad.definition_id = ?
+        WHERE r.run_id = ?`).get(params.definitionId, params.runId);
+        if (!row?.endedAt)
+            return;
+        await this.finalizeRun({
+            runId: params.runId,
+            error: getPlatformWorkflowTerminalError(row.workflowType, row.stopReason, row.error),
+        });
+    }
+    async reconcileCompletedRunningRuns(userId, definitionId) {
+        const filters = [`par.status = 'running'`, `r.ended_at IS NOT NULL`];
+        const args = [];
+        if (userId) {
+            filters.push(`par.user_id = ?`);
+            args.push(userId);
+        }
+        if (definitionId) {
+            filters.push(`par.definition_id = ?`);
+            args.push(definitionId);
+        }
+        const rows = this.db.prepare(`SELECT par.run_id as runId,
+              par.user_id as userId,
+              pad.workflow_type as workflowType,
+              r.stop_reason as stopReason,
+              r.error as error
+         FROM platform_agent_runs par
+         JOIN runs r ON r.run_id = par.run_id
+         JOIN platform_agent_definitions pad ON pad.definition_id = par.definition_id
+        WHERE ${filters.join(' AND ')}
+        ORDER BY par.created_at ASC`).all(...args);
+        for (const row of rows) {
+            await this.finalizeRun({
+                runId: row.runId,
+                error: getPlatformWorkflowTerminalError(row.workflowType, row.stopReason, row.error),
+            });
+        }
+    }
+    reconcileTerminalPlatformRunRuntimeState(userId, definitionId) {
+        const filters = [`par.status <> 'running'`, `r.ended_at IS NULL`];
+        const args = [];
+        if (userId) {
+            filters.push(`par.user_id = ?`);
+            args.push(userId);
+        }
+        if (definitionId) {
+            filters.push(`par.definition_id = ?`);
+            args.push(definitionId);
+        }
+        const rows = this.db.prepare(`SELECT par.run_id as runId,
+              par.status as status,
+              par.completed_at as completedAt,
+              par.error as error,
+              c.id as conversationId
+         FROM platform_agent_runs par
+         JOIN runs r ON r.run_id = par.run_id
+         LEFT JOIN conversations c ON c.session_key = r.session_key
+        WHERE ${filters.join(' AND ')}
+        ORDER BY par.created_at ASC`).all(...args);
+        if (rows.length === 0)
+            return;
+        const now = Date.now();
+        const transaction = this.db.transaction(() => {
+            for (const row of rows) {
+                const endedAt = row.completedAt ?? now;
+                const completed = row.status === 'completed';
+                this.db.prepare(`UPDATE runs
+              SET ended_at = COALESCE(ended_at, ?),
+                  stop_reason = COALESCE(stop_reason, ?),
+                  error = CASE
+                    WHEN ? IS NULL THEN error
+                    ELSE COALESCE(error, ?)
+                  END
+            WHERE run_id = ?
+              AND ended_at IS NULL`).run(endedAt, completed ? 'completed' : 'error', completed ? null : row.error ?? 'Platform agent run already ended.', completed ? null : row.error ?? 'Platform agent run already ended.', row.runId);
+                this.db.prepare(`DELETE FROM node_dispatch_queue WHERE run_id = ?`).run(row.runId);
+                this.db.prepare(`DELETE FROM node_host_snapshots WHERE current_run_id = ?`).run(row.runId);
+                if (row.conversationId) {
+                    this.db.prepare(`DELETE FROM conversation_prompt_queue WHERE conversation_id = ?`).run(row.conversationId);
+                    this.db.prepare(`UPDATE conversations
+                SET status = 'idle',
+                    updated_at = ?
+              WHERE id = ?
+                AND status IN ('queued', 'active', 'recovering', 'awaiting_approval')`).run(now, row.conversationId);
+                }
+            }
+        });
+        transaction();
+    }
+    async finalizeLegacyCuratorRun(runId, userId, now) {
+        await this.libraryService.finalizeOrganizeRun({ runId, userId });
+        const row = this.db.prepare(`SELECT status,
+              completed_at as completedAt,
+              error
+         FROM library_curator_runs
+        WHERE run_id = ?`).get(runId);
+        if (!row) {
+            return {
+                status: 'failed',
+                completedAt: now,
+                error: 'Legacy library curator run was not found during platform finalization.',
+                generatedCount: 0,
+            };
+        }
+        if (row.status === 'completed') {
+            return {
+                status: 'completed',
+                completedAt: row.completedAt ?? now,
+                error: null,
+                generatedCount: 0,
+            };
+        }
+        return {
+            status: 'failed',
+            completedAt: row.completedAt ?? now,
+            error: row.error ?? 'Legacy library curator run did not complete successfully.',
+            generatedCount: 0,
+        };
+    }
+    buildCustomWorkspacePath(definition, username) {
+        if (definition.definitionId === 'suggested_planner')
+            return buildPlannerWorkspacePath(this.workspaceRoot, username);
+        if (definition.definitionId === 'library_curator')
+            return buildCuratorWorkspacePath(this.workspaceRoot, username);
+        return buildGenericPlatformWorkspacePath(this.workspaceRoot, definition.definitionId, username);
+    }
+    buildDefaultRuntimeConfig(workflowType) {
+        const envVars = workflowType === 'library_curate' ? buildCuratorEnvVars() : buildPlannerEnvVars();
+        return {
+            model: envVars.ANTHROPIC_MODEL ?? 'deepseek-v4-pro',
+            reasoningEffort: null,
+            envVars,
+        };
+    }
+    pickNodeId(workflowType) {
+        return workflowType === 'library_curate'
+            ? pickLibraryNodeId(this.nodeRegistry)
+            : pickPlannerNodeId(this.nodeRegistry);
+    }
+    getPlannerLookbackDays(workflowConfig) {
+        const raw = workflowConfig.lookbackDays;
+        const value = typeof raw === 'number' ? raw : Number(raw);
+        if (!Number.isFinite(value))
+            return DEFAULT_LOOKBACK_DAYS;
+        return Math.max(1, Math.min(90, Math.round(value)));
+    }
+    getCuratorCategories(workflowConfig) {
+        const raw = workflowConfig.categories;
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((item) => typeof item === 'string' && item.trim().length > 0).map((item) => item.trim());
+    }
+    sanitizeWorkflowConfig(workflowType, workflowConfig) {
+        if (workflowType === 'planner_suggestions') {
+            return { lookbackDays: this.getPlannerLookbackDays(workflowConfig) };
+        }
+        return { categories: this.getCuratorCategories(workflowConfig) };
+    }
+    async buildResourceSnapshot(params) {
+        const snapshot = {};
+        const lookbackDays = this.getPlannerLookbackDays(params.instance.workflowConfig);
+        const resourceConfig = params.definition.resourceConfig ?? {};
+        for (const scope of params.definition.resourceScopes) {
+            if (scope === 'saved_inbox') {
+                snapshot.savedInboxItems = this.libraryService.listInboxSavedItems(params.userId);
+                continue;
+            }
+            if (scope === 'open_tasks') {
+                snapshot.openTasks = this.listAccessibleOpenTasks(params.userId, params.username);
+                continue;
+            }
+            if (scope === 'recent_messages') {
+                snapshot.recentMessages = this.listRecentMessages(params.userId, params.username, lookbackDays, resourceConfig);
+                continue;
+            }
+            if (scope === 'conversation_summaries') {
+                snapshot.conversationSummaries = this.listConversationSummaries(params.userId, lookbackDays, resourceConfig);
+                continue;
+            }
+            if (scope === 'agent_memory') {
+                snapshot.agentMemory = await this.readAccessibleAgentMemory(params.userId, resourceConfig);
+                continue;
+            }
+            if (scope === 'agent_notes') {
+                snapshot.agentNotes = await this.readAccessibleAgentNotes(params.userId, resourceConfig);
+                continue;
+            }
+            if (scope === 'personal_library_inventory') {
+                snapshot.personalLibraryInventory = await this.libraryService.listDocuments(params.userId, undefined, 'personal');
+                continue;
+            }
+            if (scope === 'personal_library_documents') {
+                snapshot.personalLibraryDocuments = await this.readPersonalLibraryDocuments(params.userId, resourceConfig);
+            }
+        }
+        return snapshot;
+    }
+    listAccessibleOpenTasks(userId, username) {
+        const directTarget = `dm:@${username}`;
+        return 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,
+              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
+        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);
+    }
+    listRecentMessages(userId, username, lookbackDays, resourceConfig) {
+        const directTarget = `dm:@${username}`;
+        const directThreadTargetGlob = `${directTarget}:*`;
+        const since = Date.now() - lookbackDays * 24 * 60 * 60 * 1000;
+        const limit = Math.max(5, Math.min(100, Number(resourceConfig.maxRecentMessages ?? 30) || 30));
+        return 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 ?`).all(since, userId, userId, directTarget, directThreadTargetGlob, limit);
+    }
+    listConversationSummaries(userId, lookbackDays, resourceConfig) {
+        const since = Date.now() - lookbackDays * 24 * 60 * 60 * 1000;
+        const limit = Math.max(5, Math.min(50, Number(resourceConfig.maxConversationSummaries ?? 20) || 20));
+        const rows = 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 ?`).all(userId, since, limit);
+        return rows.map((summary) => ({
+            conversationId: summary.conversationId,
+            replyTarget: summary.replyTarget,
+            updatedAt: summary.updatedAt,
+            summary: parseJsonRecord(summary.summaryJson),
+        }));
+    }
+    async readAccessibleAgentMemory(userId, resourceConfig) {
+        const agents = this.listAccessibleSnapshotAgents(userId, resourceConfig);
+        const results = [];
+        for (const agent of agents) {
+            const content = await this.readWorkspaceTextFile(agent, 'MEMORY.md');
+            if (!content)
+                continue;
+            results.push({
+                agentId: agent.agentId,
+                agentName: agent.name,
+                content,
+            });
+        }
+        return results;
+    }
+    async readAccessibleAgentNotes(userId, resourceConfig) {
+        const agents = this.listAccessibleSnapshotAgents(userId, resourceConfig);
+        const results = [];
+        const maxNotesPerAgent = Math.max(1, Math.min(10, Number(resourceConfig.maxNotesPerAgent ?? 5) || 5));
+        for (const agent of agents) {
+            if (!agent.workspacePath?.trim())
+                continue;
+            try {
+                const listing = agent.nodeId
+                    ? await this.workspaceBroker.listDirectory(agent.nodeId, agent.workspacePath, 'notes', { scaffold: false, agentName: agent.name, limit: 50 })
+                    : null;
+                const files = (listing?.entries ?? [])
+                    .filter((entry) => entry.kind === 'file' && entry.path.toLowerCase().endsWith('.md'))
+                    .slice(0, maxNotesPerAgent);
+                const notes = [];
+                for (const file of files) {
+                    const content = await this.readWorkspaceTextFile(agent, file.path);
+                    if (!content)
+                        continue;
+                    notes.push({ relativePath: file.path, content });
+                }
+                if (notes.length > 0) {
+                    results.push({
+                        agentId: agent.agentId,
+                        agentName: agent.name,
+                        notes,
+                    });
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return results;
+    }
+    async readPersonalLibraryDocuments(userId, resourceConfig) {
+        const docs = await this.libraryService.listDocuments(userId, undefined, 'personal');
+        const maxDocuments = Math.max(1, Math.min(50, Number(resourceConfig.maxLibraryDocuments ?? 20) || 20));
+        const selected = docs.slice(0, maxDocuments);
+        const results = [];
+        for (const doc of selected) {
+            try {
+                const file = await this.libraryService.readLibraryFile(userId, doc.relativePath, 'personal');
+                results.push({
+                    title: doc.title,
+                    category: doc.category,
+                    topicPath: doc.topicPath,
+                    relativePath: doc.relativePath,
+                    summary: doc.summary,
+                    content: file.content,
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+        return results;
+    }
+    listAccessibleSnapshotAgents(userId, resourceConfig) {
+        const requestedAgentIds = Array.isArray(resourceConfig.agentIds)
+            ? resourceConfig.agentIds.filter((value) => typeof value === 'string' && value.trim().length > 0).map((value) => value.trim())
+            : [];
+        const rows = this.db.prepare(`SELECT a.agent_id as agentId
+         FROM agents a
+         JOIN user_agent_access uaa ON uaa.agent_id = a.agent_id
+        WHERE uaa.user_id = ?
+          AND a.deleted_at IS NULL
+        ORDER BY a.updated_at DESC`).all(userId);
+        const agents = rows
+            .map((row) => this.conversationManager.getAgent(row.agentId))
+            .filter((agent) => {
+            if (!agent)
+                return false;
+            return agent.agentRole !== 'platform_agent' && agent.agentRole !== 'library_curator' && agent.agentRole !== 'suggested_planner';
+        });
+        if (requestedAgentIds.length > 0) {
+            const allowed = new Set(requestedAgentIds);
+            return agents.filter((agent) => allowed.has(agent.agentId));
+        }
+        return agents.slice(0, 6);
+    }
+    async readWorkspaceTextFile(agent, relativePath) {
+        if (!agent.workspacePath?.trim())
+            return null;
+        try {
+            if (agent.nodeId) {
+                const result = await this.workspaceBroker.readFile(agent.nodeId, agent.workspacePath, relativePath, {
+                    scaffold: false,
+                    agentName: agent.name,
+                });
+                return result.content;
+            }
+            const absolutePath = path.join(agent.workspacePath, relativePath);
+            return fs.existsSync(absolutePath) ? fs.readFileSync(absolutePath, 'utf8') : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    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));
+    }
+    getRunOutputText(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 {
+                continue;
+            }
+        }
+        return byType['content.delta'].join('').trim() || byType['activity.delta'].join('').trim();
+    }
+    scheduleNextRun(userId, definitionId, now, scheduleIntervalMs) {
+        this.db.prepare(`UPDATE platform_agent_instances
+          SET next_run_at = ?,
+              updated_at = ?
+        WHERE user_id = ? AND definition_id = ?`).run(now + scheduleIntervalMs, now, userId, definitionId);
+    }
+}