fuli-context 0.7.3 → 0.7.4-beta.1

package/src/mcp/create-mcp-server.js

@@ -7,6 +7,7 @@ import { MCP_INSTRUCTIONS } from './instructions.js';
 import { createProjectActionPreviewTokens } from './project-action-preview-tokens.js';
 import { createCommonKnowledgePreviewTokens } from './common-knowledge-preview-tokens.js';
 import { auditLifecycleTool } from './lifecycle-audit.js';
+import { registerFuliContextResources } from './context-resources.js';
 import { annotationsFor } from './tool-annotations.js';
 import {
   errorToolResult,
@@ -15,31 +16,58 @@ import {
   successToolResult
 } from './tool-result.js';
 import { jsonSchemaToZod, openObjectSchema } from './tool-schema.js';
+import {
+  mcpHostSessionId,
+  nativeCodexThreadId,
+  normalizeAgentSessionInput
+} from './session-id.js';
 
 const TOOL_RESULT_LIMIT_BYTES = Object.freeze({
   begin_task_context: 16 * 1024,
   get_collaboration_preferences: 16 * 1024,
+  get_user_taste_skill: 32 * 1024,
   search_knowledge_graph: 32 * 1024,
   search_connected_knowledge: 64 * 1024,
   search_current_project_knowledge: 64 * 1024,
   discover_common_knowledge_candidates: 32 * 1024,
+  discover_personal_global_preference_candidates: 32 * 1024,
+  preview_personal_global_preference_decision: 32 * 1024,
   list_personal_projects: 32 * 1024,
-  list_knowledge_review_candidates: 32 * 1024
+  list_knowledge_review_candidates: 32 * 1024,
+  list_workflow_candidates: 32 * 1024,
+  recommend_next_workflow_steps: 32 * 1024
 });
 
-export function createMcpServer(app) {
+export function createMcpServer(
+  app,
+  { env = process.env, clock = () => new Date() } = {}
+) {
   const server = new McpServer(
     { name: 'fuli', version: FULI_VERSION },
     { instructions: MCP_INSTRUCTIONS }
   );
 
-  const tools = createToolMap(app, createProjectActionPreviewTokens());
+  const nativeThreadId = nativeCodexThreadId(env);
+  const tools = createToolMap(
+    app,
+    createProjectActionPreviewTokens(),
+    nativeThreadId,
+    mcpHostSessionId(env),
+    clock
+  );
   for (const tool of tools.values()) registerTool(server, tool);
+  registerFuliContextResources(server, app);
   registerCallHandler(server, tools);
   return server;
 }
 
-function createToolMap(app, projectActionPreviews) {
+function createToolMap(
+  app,
+  projectActionPreviews,
+  nativeThreadId,
+  hostSessionId,
+  clock
+) {
   const commonKnowledgePreviews = createCommonKnowledgePreviewTokens();
   return new Map(listAgentTools().map((definition) => [definition.name, {
     definition,
@@ -47,7 +75,13 @@ function createToolMap(app, projectActionPreviews) {
     invoke: (input) => invokeAgentTool(
       app,
       definition.name,
-      input,
+      normalizeAgentSessionInput(
+        definition.name,
+        input,
+        nativeThreadId,
+        hostSessionId,
+        clock
+      ),
       projectActionPreviews,
       commonKnowledgePreviews
     )

package/src/mcp/instructions.js

@@ -1,9 +1,7 @@
 export const MCP_INSTRUCTIONS = [
-  "Each user task: apply hook-provided task context from begin_task_context. Otherwise, before other tools/answer, call exactly get_collaboration_preferences with projectPath=cwd and taskPrompt=current user request as fallback; never substitute a project action/Fuli tool. Apply all effective_preferences: personal-global everywhere plus only Fuli's matched project. Resolve relevant deferred_conflict first. Never guess personalProjectId. Writes enforce preferences in the actual payload; final text is not compliance.",
-  'Before asking the user to repeat a stable project fact or method, inspect task_knowledge_recall. On miss use search_current_project_knowledge with 1-4 focused action, artifact, target-system, or identifier queries; never use the whole conversational request as the only query. Search the exact active child first, then inheritable parent PART_OF/USES_KNOWLEDGE_FROM knowledge within two hops; child stable keys override. Never inherit project preferences or traverse RELATED_TO.',
-  'Before claiming facts unknown, use search_knowledge_graph. Use exact IDs for extra projects. Widen a miss to all_local_confirmed only after consent, then rg only in the safe current repo/workspace. Never scan outside it. Live state needs deployment/monitoring/Git MCP evidence. External/public evidence: search_connected_knowledge; agent_decide is response-only.',
-  'Use record_decision_trace for confirmed choices and record_knowledge_feedback when knowledge is rejected, contradicted, outdated, or fails validation.',
-  'Batch durable confirmed knowledge via capture_session_knowledge in exact scope; never secrets, transcripts, or guesses. Finish once with checkpoint_task_knowledge: capture_candidates or retain_nothing.',
-  'After material personal-knowledge use call record_knowledge_usage; retrieval alone never counts or permits public use.',
-  'Terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown; append sourceMarker.markdown unchanged on match. On miss use noMatchSourceMarker leadMarkdown only (empty markdown). Never wrap markers in HTML.'
+  'Each user task: hook-provided task context from begin_task_context. Otherwise, before other tools/answer, call exactly get_collaboration_preferences with projectPath=cwd and taskPrompt=current user request as fallback; never substitute a project action. Apply all effective_preferences: personal-global everywhere, matched project, authorized inheritable parent. For taste/judgment, call get_user_taste_skill; never replaces a user-authored Skill. FULI fuli:// exposes exact projects/global taste; an @ selection is explicit and adds no project. Resolve relevant deferred_conflict first; never guess personalProjectId. Writes enforce actual payload; final text is not compliance.',
+  'Before asking user to repeat a stable project fact or method, inspect task_knowledge_recall. On miss call search_current_project_knowledge with focused action, artifact, target-system, or identifier queries; never use the whole conversational request as the only query. Search active child first, then inheritable parent via authorized PART_OF/USES_KNOWLEDGE_FROM, 2 hops; parent prefs need descendants/selected_projects; local_only/RELATED_TO never inherit; authority > distance > weight; equal conflicts defer.',
+  'Before saying unknown, call search_knowledge_graph. Use exact IDs for extra projects. RELATED_TO suggests; ask first. Use all_local_confirmed only after consent, then rg only in safe current repo/workspace; never scan outside it. Live state: monitoring/Git MCP. External/public: search_connected_knowledge; agent_decide is response-only.',
+  'Use record_decision_trace; record_knowledge_feedback on rejected/outdated/failed items. Batch durable confirmed knowledge with capture_session_knowledge; no secrets/guesses. Finish with checkpoint_task_knowledge: capture_candidates or retain_nothing. Then record_knowledge_usage.',
+  'Terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown and append sourceMarker.markdown unchanged on match. On miss use noMatchSourceMarker leadMarkdown only (empty markdown); never wrap markers in HTML.'
 ].join(' ');

package/src/mcp/session-id.js

@@ -0,0 +1,60 @@
+import { randomUUID } from 'node:crypto';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const WORKFLOW_OBSERVATION_TOOL = 'record_workflow_transition_observation';
+
+const SESSION_ID_TOOLS = new Set([
+  'begin_task_context',
+  'verify_task_checkpoint',
+  'capture_session_knowledge',
+  'record_decision_trace',
+  'record_knowledge_usage',
+  'record_knowledge_feedback'
+]);
+
+export function nativeCodexThreadId(env = process.env) {
+  const value = typeof env?.CODEX_THREAD_ID === 'string'
+    ? env.CODEX_THREAD_ID.trim()
+    : '';
+  return UUID.test(value) ? value : null;
+}
+
+export function mcpHostSessionId(
+  env = process.env,
+  idFactory = randomUUID
+) {
+  return nativeCodexThreadId(env) ?? `fuli-host-${idFactory()}`;
+}
+
+export function normalizeAgentSessionInput(
+  name,
+  input,
+  nativeThreadId,
+  hostSessionId = nativeThreadId,
+  clock = () => new Date()
+) {
+  if (name === WORKFLOW_OBSERVATION_TOOL) {
+    if (!hostSessionId) {
+      throw new TypeError('Workflow observations require an MCP host session');
+    }
+    const {
+      sessionId: _sessionId,
+      idempotencyKey: _idempotencyKey,
+      observedAt: _observedAt,
+      hostSessionId: _hostSessionId,
+      hostObservedAt: _hostObservedAt,
+      ...safeInput
+    } = input ?? {};
+    return {
+      ...safeInput,
+      hostSessionId,
+      hostObservedAt: clock().toISOString()
+    };
+  }
+  if (!nativeThreadId || !SESSION_ID_TOOLS.has(name)) return input;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
+  if (typeof input.sessionId !== 'string' || input.sessionId.trim() === nativeThreadId) {
+    return input;
+  }
+  return { ...input, sessionId: nativeThreadId };
+}

package/src/mcp/task-context-registry.js

@@ -1,7 +1,16 @@
 import { randomUUID } from 'node:crypto';
 
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+
 const MAX_ACTIVE_SESSIONS = 256;
 
+function unknownTokenError() {
+  return new ApplicationError(
+    ApplicationErrorCode.NOT_FOUND,
+    'Fuli task context token is unknown or superseded. Call begin_task_context for the current session and use the token it returns.'
+  );
+}
+
 export class TaskContextRegistry {
   constructor({ tokenFactory = () => `fuli-task-${randomUUID()}` } = {}) {
     this.tokenFactory = tokenFactory;
@@ -33,10 +42,13 @@ export class TaskContextRegistry {
   checkpoint(token, checkpoint) {
     assertNonEmpty(token, 'taskContextToken');
     const task = this.tokens.get(token);
-    if (!task) throw new TypeError('Unknown or expired Fuli task context token');
+    if (!task) throw unknownTokenError();
     if (task.checkpoint) {
       if (sameCheckpoint(task.checkpoint, checkpoint)) return task;
-      throw new TypeError('Fuli task context has already been checkpointed');
+      throw new ApplicationError(
+        ApplicationErrorCode.VALIDATION,
+        'Fuli task context has already been checkpointed with a different disposition'
+      );
     }
     task.checkpoint = Object.freeze({ ...checkpoint });
     return task;
@@ -45,7 +57,7 @@ export class TaskContextRegistry {
   context(token) {
     assertNonEmpty(token, 'taskContextToken');
     const task = this.tokens.get(token);
-    if (!task) throw new TypeError('Unknown or expired Fuli task context token');
+    if (!task) throw unknownTokenError();
     return task;
   }
 

package/src/mcp/tool-annotations.js

@@ -2,10 +2,14 @@ const READ_TOOLS = new Set([
   'verify_task_checkpoint',
   'search_current_project_knowledge',
   'discover_common_knowledge_candidates',
+  'discover_personal_global_preference_candidates',
+  'preview_personal_global_preference_decision',
   'preview_common_knowledge_promotion',
   'list_knowledge_spaces',
   'list_personal_projects',
   'list_knowledge_review_candidates',
+  'list_workflow_candidates',
+  'recommend_next_workflow_steps',
   'preview_personal_project_action',
   'list_project_releases',
   'list_project_relations',
@@ -18,8 +22,10 @@ const WRITE_TOOLS = new Set([
   'begin_task_context',
   'checkpoint_task_knowledge',
   'get_collaboration_preferences',
+  'get_user_taste_skill',
   'resolve_deferred_preference_conflict',
   'capture_session_knowledge',
+  'record_workflow_transition_observation',
   'record_decision_trace',
   'search_knowledge_graph',
   'search_connected_knowledge',
@@ -35,7 +41,6 @@ const WRITE_TOOLS = new Set([
   'finish_knowledge_review',
   'revise_personal_knowledge',
   'reassign_personal_knowledge',
-  'set_personal_preference_scope',
   'apply_personal_project_action',
   'publish_personal_project',
   'create_project_relation',
@@ -67,8 +72,10 @@ export function annotationsFor(name) {
       name === 'publish_personal_project' || name === 'unsubscribe_public_project' ||
       name === 'record_knowledge_usage' || name === 'record_decision_trace' ||
       name === 'record_knowledge_feedback' ||
+      name === 'record_workflow_transition_observation' ||
       name === 'checkpoint_task_knowledge',
     openWorldHint: name === 'capture_session_knowledge' ||
+      name === 'record_workflow_transition_observation' ||
       name === 'search_connected_knowledge' ||
       name === 'record_decision_trace' ||
       name === 'record_knowledge_feedback' ||

package/src/mcp/tool-result.js

@@ -15,6 +15,7 @@ const RESULT_PROPERTY_LIMIT = 64;
 const RESULT_DEPTH_LIMIT = 8;
 const MESSAGE_LIMIT = 240;
 const TRUNCATION_MARKER = '...[truncated]';
+const VALIDATION_ERROR_LIMIT = 5;
 
 export function successToolResult(value, { limitBytes = RESULT_LIMIT_BYTES } = {}) {
   const state = { truncated: false };
@@ -63,17 +64,40 @@ export function errorToolResult(error) {
   const message = controlled
     ? applicationErrorMessage(error)
     : 'Tool execution failed';
-  const structuredContent = { error: { code, message } };
+  const validationErrors = controlled ? reportedValidationErrors(error) : [];
+  const structuredContent = {
+    error: {
+      code,
+      message,
+      ...(validationErrors.length ? { validationErrors } : {})
+    }
+  };
+  const detail = validationErrors
+    .map(({ field, message: reason }) => (field ? `${field} — ${reason}` : reason))
+    .join('; ');
   return {
-    content: [{ type: 'text', text: `${code}: ${message}` }],
+    content: [{
+      type: 'text',
+      text: detail ? `${code}: ${message}\n${detail}` : `${code}: ${message}`
+    }],
     structuredContent,
     isError: true
   };
 }
 
+function reportedValidationErrors(error) {
+  if (!Array.isArray(error?.validationErrors)) return [];
+  return error.validationErrors
+    .filter((entry) => entry && typeof entry.message === 'string' && entry.message.trim())
+    .slice(0, VALIDATION_ERROR_LIMIT)
+    .map(({ field, message }) => ({
+      field: typeof field === 'string' ? boundedMessage(field) : '',
+      message: boundedMessage(message)
+    }));
+}
+
 export function applicationErrorMessage(error) {
-  const stableMessage = String(error.message).split(':', 1)[0];
-  return boundedMessage(stableMessage);
+  return boundedMessage(String(error.message));
 }
 
 export function protocolErrorResult(message) {

package/src/server.js

@@ -66,7 +66,6 @@ export async function createServer(options = {}) {
         activeLan: lanEnabled
       })
     : null);
-
   for (let attempt = 0; attempt < 20; attempt += 1) {
     let authority = null;
     let allowedLanAuthorities = [];

package/src/setup/claude-code-config.js

@@ -38,7 +38,9 @@ export function connectClaudeCode(agent, context, {
       }
     }
   };
-  const nextSettings = withManagedHooks(settings);
+  const nextSettings = withManagedHooks(settings, {
+    hookTimeoutSec: context.hookTimeoutSec
+  });
   const registrationChanged = !sameJson(current, next);
   const hooksChanged = !sameJson(settings, nextSettings);
   if (registrationChanged) writeConfig(agent.configPath, next);
@@ -108,7 +110,8 @@ export function hasCurrentClaudeCodeHooks(settings) {
   ));
 }
 
-function withManagedHooks(settings) {
+function withManagedHooks(settings, { hookTimeoutSec = 30 } = {}) {
+  const normalizedHookTimeoutSec = positiveHookTimeout(hookTimeoutSec);
   const clean = withoutManagedHooks(settings);
   const hooks = { ...(clean.hooks ?? {}) };
   hooks.UserPromptSubmit = [
@@ -117,14 +120,15 @@ function withManagedHooks(settings) {
       sessionId: '${session_id}',
       projectPath: '${cwd}',
       taskPrompt: '${prompt}'
-    }, 'Loading Fuli task context')
+    }, 'Loading Fuli task context', normalizedHookTimeoutSec)
   ];
   hooks.Stop = [
     ...(hooks.Stop ?? []),
     managedHookGroup(
       'verify_task_checkpoint',
       { sessionId: '${session_id}' },
-      'Checking Fuli task checkpoint'
+      'Checking Fuli task checkpoint',
+      normalizedHookTimeoutSec
     )
   ];
   return { ...clean, hooks };
@@ -149,19 +153,26 @@ function withoutManagedHooks(settings) {
   return { ...settings, hooks };
 }
 
-function managedHookGroup(tool, input, statusMessage) {
+function managedHookGroup(tool, input, statusMessage, timeout) {
   return {
     hooks: [{
       type: 'mcp_tool',
       server: FULI_SERVER,
       tool,
       input,
-      timeout: 30,
+      timeout,
       statusMessage
     }]
   };
 }
 
+function positiveHookTimeout(value) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {
+    throw new TypeError('Claude Code hook timeout must be a positive safe integer');
+  }
+  return value;
+}
+
 function isManagedHook(hook, tool = null) {
   return hook?.type === 'mcp_tool'
     && hook.server === FULI_SERVER

package/src/setup/graph-runtime.js

@@ -79,7 +79,9 @@ export async function ensureGraphRuntime(input, dependencies = {}) {
     deps.secureFile(input.paths.graphRuntimeConfigPath);
   } else {
     const synchronized = synchronizeManagedProviderUrls(config, urls, {
-      personalOnly: input.personalOnly === true
+      personalOnly: input.personalOnly === true,
+      workflowObservationToken:
+        secrets.FULI_PERSONAL_WORKFLOW_OBSERVATION_TOKEN
     });
     if (synchronized.changed) {
       await reconcileManagedWorkspaceSubscriptions({
@@ -154,6 +156,10 @@ function ensureProviderEnvironment(path, settings, deps) {
     FULI_PERSONAL_NEO4J_PASSWORD: previous.FULI_PERSONAL_NEO4J_PASSWORD ?? secret(),
     FULI_WORKSPACE_NEO4J_PASSWORD: previous.FULI_WORKSPACE_NEO4J_PASSWORD ?? secret(),
     FULI_PERSONAL_BOOTSTRAP_TOKEN: previous.FULI_PERSONAL_BOOTSTRAP_TOKEN ?? secret(),
+    FULI_PERSONAL_HUMAN_REVIEW_TOKEN:
+      previous.FULI_PERSONAL_HUMAN_REVIEW_TOKEN ?? secret(),
+    FULI_PERSONAL_WORKFLOW_OBSERVATION_TOKEN:
+      previous.FULI_PERSONAL_WORKFLOW_OBSERVATION_TOKEN ?? secret(),
     FULI_WORKSPACE_BOOTSTRAP_TOKEN: previous.FULI_WORKSPACE_BOOTSTRAP_TOKEN ?? secret(),
     FULI_PERSONAL_NEO4J_HTTP_PORT: String(settings.ports.personalNeo4jHttp),
     FULI_PERSONAL_NEO4J_BOLT_PORT: String(settings.ports.personalNeo4jBolt),
@@ -186,6 +192,8 @@ async function bootstrapGraph({ urls, personalSpaceName, secrets, personalOnly,
     personal: {
       providerUrl: urls.personal,
       accessToken: personalIdentity.access_token,
+      workflowObservationToken:
+        secrets.FULI_PERSONAL_WORKFLOW_OBSERVATION_TOKEN,
       principalId: personalIdentity.principal_id,
       spaceId: personalSpace.id
     },
@@ -224,10 +232,20 @@ async function bootstrapGraph({ urls, personalSpaceName, secrets, personalOnly,
   return config;
 }
 
-export function synchronizeManagedProviderUrls(config, urls, { personalOnly = true } = {}) {
+export function synchronizeManagedProviderUrls(config, urls, {
+  personalOnly = true,
+  workflowObservationToken = null
+} = {}) {
   const next = structuredClone(config);
   let changed = next.personal?.providerUrl !== urls.personal;
   next.personal.providerUrl = urls.personal;
+  if (
+    nonEmpty(workflowObservationToken) &&
+    next.personal.workflowObservationToken !== workflowObservationToken
+  ) {
+    next.personal.workflowObservationToken = workflowObservationToken;
+    changed = true;
+  }
   if (!personalOnly) {
     for (const workspace of next.workspaces ?? []) {
       if (!isManagedWorkspace(workspace)) continue;

package/src/system/runtime-settings.js

@@ -5,6 +5,15 @@ import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
 
 export const RUNTIME_SETTINGS_VERSION = 1;
 export const RESOURCE_REFRESH_OPTIONS = Object.freeze([5, 10, 30, 60]);
+export const CONVERSATION_LAUNCHER_APPLICATIONS = Object.freeze([
+  'codex',
+  'claude_code',
+  'cursor',
+  'gemini_cli',
+  'kiro',
+  'other'
+]);
+export const CONVERSATION_ID_FORMATS = Object.freeze(['any', 'uuid']);
 export const PORT_KEYS = Object.freeze([
   'console',
   'personalProvider',
@@ -15,6 +24,45 @@ export const PORT_KEYS = Object.freeze([
   'workspaceNeo4jBolt'
 ]);
 
+export const DEFAULT_CONVERSATION_LAUNCHERS = deepFreeze({
+  codex: {
+    enabled: true,
+    idFormat: 'uuid',
+    appName: 'Codex',
+    urlTemplate: 'codex://threads/{id}'
+  },
+  claude_code: {
+    enabled: false,
+    idFormat: 'any',
+    appName: 'Claude Code',
+    urlTemplate: ''
+  },
+  cursor: {
+    enabled: false,
+    idFormat: 'any',
+    appName: 'Cursor',
+    urlTemplate: ''
+  },
+  gemini_cli: {
+    enabled: false,
+    idFormat: 'any',
+    appName: 'Gemini CLI',
+    urlTemplate: ''
+  },
+  kiro: {
+    enabled: false,
+    idFormat: 'any',
+    appName: 'Kiro',
+    urlTemplate: ''
+  },
+  other: {
+    enabled: false,
+    idFormat: 'any',
+    appName: 'Other Agent',
+    urlTemplate: ''
+  }
+});
+
 export const DEFAULT_RUNTIME_SETTINGS = deepFreeze({
   version: RUNTIME_SETTINGS_VERSION,
   ports: {
@@ -27,7 +75,8 @@ export const DEFAULT_RUNTIME_SETTINGS = deepFreeze({
     workspaceNeo4jBolt: 7688
   },
   lanAccess: false,
-  resourceRefreshSeconds: 5
+  resourceRefreshSeconds: 5,
+  conversationLaunchers: DEFAULT_CONVERSATION_LAUNCHERS
 });
 
 export function readRuntimeSettings(path, {
@@ -81,14 +130,69 @@ export function normalizeRuntimeSettings(input, {
   if (!RESOURCE_REFRESH_OPTIONS.includes(resourceRefreshSeconds)) {
     throw new TypeError('resourceRefreshSeconds must be 5, 10, 30, or 60');
   }
+  const conversationLaunchers = normalizeConversationLaunchers(
+    input.conversationLaunchers,
+    { base: base.conversationLaunchers ?? DEFAULT_CONVERSATION_LAUNCHERS }
+  );
   return {
     version: RUNTIME_SETTINGS_VERSION,
     ports,
     lanAccess,
-    resourceRefreshSeconds
+    resourceRefreshSeconds,
+    conversationLaunchers
   };
 }
 
+export function normalizeConversationLaunchers(input, {
+  base = DEFAULT_CONVERSATION_LAUNCHERS
+} = {}) {
+  if (input !== undefined && (!input || typeof input !== 'object' || Array.isArray(input))) {
+    throw new TypeError('conversationLaunchers must be an object');
+  }
+  for (const key of Object.keys(input ?? {})) {
+    if (!CONVERSATION_LAUNCHER_APPLICATIONS.includes(key)) {
+      throw new TypeError(`Unsupported conversation launcher: ${key}`);
+    }
+  }
+  return Object.fromEntries(CONVERSATION_LAUNCHER_APPLICATIONS.map((application) => {
+    const fallback = base[application] ?? DEFAULT_CONVERSATION_LAUNCHERS[application];
+    const candidate = input?.[application] ?? fallback;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      throw new TypeError(`${application} conversation launcher must be an object`);
+    }
+    const enabled = candidate.enabled ?? fallback.enabled;
+    if (typeof enabled !== 'boolean') {
+      throw new TypeError(`${application} conversation launcher enabled must be a boolean`);
+    }
+    const idFormat = candidate.idFormat ?? fallback.idFormat;
+    if (!CONVERSATION_ID_FORMATS.includes(idFormat)) {
+      throw new TypeError(`${application} conversation launcher idFormat is unsupported`);
+    }
+    const appName = launcherText(
+      candidate.appName ?? fallback.appName,
+      `${application} conversation launcher appName`,
+      64
+    );
+    const urlTemplate = launcherText(
+      candidate.urlTemplate ?? fallback.urlTemplate,
+      `${application} conversation launcher urlTemplate`,
+      1024
+    );
+    if (enabled && !appName) {
+      throw new TypeError(`${application} conversation launcher appName is required`);
+    }
+    if (urlTemplate && !validConversationUrlTemplate(urlTemplate)) {
+      throw new TypeError(
+        `${application} conversation launcher urlTemplate must use a safe URL scheme and contain {id}`
+      );
+    }
+    if (enabled && !urlTemplate) {
+      throw new TypeError(`${application} conversation launcher urlTemplate is required`);
+    }
+    return [application, { enabled, idFormat, appName, urlTemplate }];
+  }));
+}
+
 export function runtimeSettingsWithOverrides(settings, {
   consolePort = null,
   lanAccess = null
@@ -122,6 +226,21 @@ function validPort(value, key) {
   return value;
 }
 
+function launcherText(value, label, maximumLength) {
+  if (typeof value !== 'string') throw new TypeError(`${label} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed.length > maximumLength || /[\u0000-\u001f\u007f]/.test(trimmed)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return trimmed;
+}
+
+function validConversationUrlTemplate(value) {
+  if (value.split('{id}').length !== 2 || /\s/.test(value)) return false;
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+  return Boolean(scheme) && !['about', 'blob', 'data', 'file', 'javascript'].includes(scheme);
+}
+
 function deepFreeze(value) {
   Object.freeze(value);
   for (const child of Object.values(value)) {

package/src/system/system-service.js

@@ -86,7 +86,11 @@ function settingsResult(configured, active) {
     configured,
     active,
     restartRequired: !runtimeSettingsEqual(
-      { ...configured, resourceRefreshSeconds: active.resourceRefreshSeconds },
+      {
+        ...configured,
+        resourceRefreshSeconds: active.resourceRefreshSeconds,
+        conversationLaunchers: active.conversationLaunchers
+      },
       active
     )
   };