fuli-context 0.7.6 → 0.7.7

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

@@ -1,7 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
 
 import { callAgentTool, listAgentTools } from '../agent-tools.js';
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
 import { FULI_VERSION } from '../package-metadata.js';
 import { MCP_INSTRUCTIONS } from './instructions.js';
 import { createProjectActionPreviewTokens } from './project-action-preview-tokens.js';
@@ -24,8 +28,13 @@ import {
 } from './session-id.js';
 
 const TOOL_RESULT_LIMIT_BYTES = Object.freeze({
-  begin_task_context: 16 * 1024,
-  get_collaboration_preferences: 16 * 1024,
+  list_employee_templates: 32 * 1024,
+  recruit_employee: 64 * 1024,
+  list_employee_tools: 64 * 1024,
+  call_employee_tool: 64 * 1024,
+  begin_task_context: 64 * 1024,
+  checkpoint_task_knowledge: 16 * 1024,
+  get_collaboration_preferences: 64 * 1024,
   get_user_taste_skill: 32 * 1024,
   search_knowledge_graph: 32 * 1024,
   search_connected_knowledge: 64 * 1024,
@@ -38,6 +47,8 @@ const TOOL_RESULT_LIMIT_BYTES = Object.freeze({
   get_project_agent: 32 * 1024,
   list_project_agent_assignments: 32 * 1024,
   get_project_agent_context: 64 * 1024,
+  get_project_agent_memory: 128 * 1024,
+  checkpoint_project_agent_memory: 64 * 1024,
   coordinate_project_agent_task: 256 * 1024,
   acquire_runtime_lease: 4 * 1024,
   refresh_runtime_lease: 4 * 1024,
@@ -63,33 +74,46 @@ export function createMcpServer(
     env = process.env,
     clock = () => new Date(),
     sourceApplication = nativeCodexThreadId(env) ? 'codex' : 'other',
-    withRuntimeLease = (_owner, operation) => operation()
+    withRuntimeLease = (_owner, operation) => operation(),
+    hostSessionId = null,
+    instructions = MCP_INSTRUCTIONS,
+    toolNames = null,
+    prepareToolInput = (_name, input) => input,
+    registerResources = true
   } = {}
 ) {
   const server = new McpServer(
     { name: 'fuli', version: FULI_VERSION },
-    { instructions: MCP_INSTRUCTIONS }
+    { instructions }
   );
 
-  const nativeThreadId = nativeCodexThreadId(env);
   const authoritativeSourceApplication = normalizeMcpSourceApplication(
     sourceApplication
   );
+  const nativeThreadId = authoritativeSourceApplication === 'codex' ? nativeCodexThreadId(env) : null;
   const tools = createToolMap(
     app,
     createProjectActionPreviewTokens(),
     nativeThreadId,
-    mcpHostSessionId(env),
+    hostSessionId ?? mcpHostSessionId(authoritativeSourceApplication === 'codex' ? env : {}),
     clock,
     authoritativeSourceApplication,
-    withRuntimeLease
+    withRuntimeLease,
+    toolNames,
+    prepareToolInput
   );
   for (const tool of tools.values()) registerTool(server, tool);
-  registerFuliContextResources(server, app, { withRuntimeLease });
+  if (!tools.size) registerEmptyToolList(server);
+  if (registerResources) registerFuliContextResources(server, app, { withRuntimeLease });
   registerCallHandler(server, tools);
   return server;
 }
 
+function registerEmptyToolList(server) {
+  server.server.registerCapabilities({ tools: { listChanged: true } });
+  server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [] }));
+}
+
 function createToolMap(
   app,
   projectActionPreviews,
@@ -97,29 +121,52 @@ function createToolMap(
   hostSessionId,
   clock,
   sourceApplication,
-  withRuntimeLease
+  withRuntimeLease,
+  toolNames,
+  prepareToolInput
 ) {
   const commonKnowledgePreviews = createCommonKnowledgePreviewTokens();
-  return new Map(listAgentTools().map((definition) => [definition.name, {
+  if (toolNames !== null && !Array.isArray(toolNames)) {
+    throw new TypeError('MCP toolNames must be an array or null');
+  }
+  const definitions = listAgentTools();
+  const allowedTools = toolNames === null ? null : new Set(toolNames);
+  if (allowedTools) {
+    const available = new Set(definitions.map(({ name }) => name));
+    const unknown = [...allowedTools].filter((name) => !available.has(name));
+    if (unknown.length) {
+      throw new TypeError(
+        `Unknown MCP tool name${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`
+      );
+    }
+  }
+  return new Map(definitions
+    .filter((definition) => !allowedTools || allowedTools.has(definition.name))
+    .map((definition) => [definition.name, {
     definition,
     schema: jsonSchemaToZod(definition.inputSchema),
-    invoke: (input) => withRuntimeLease(
-      `mcp-tool:${definition.name}`,
-      () => invokeAgentTool(
-        app,
-        definition.name,
-        normalizeAgentSessionInput(
+    invoke: (input, requestContext = null) => {
+      requestContext?.signal?.throwIfAborted?.();
+      return withRuntimeLease(
+        `mcp-tool:${definition.name}`,
+        () => invokeAgentTool(
+          app,
           definition.name,
-          input,
-          nativeThreadId,
-          hostSessionId,
-          clock,
-          sourceApplication
+          normalizeAgentSessionInput(
+            definition.name,
+            prepareToolInput(definition.name, input),
+            nativeThreadId,
+            hostSessionId,
+            clock,
+            sourceApplication
+          ),
+          projectActionPreviews,
+          commonKnowledgePreviews,
+          requestContext
         ),
-        projectActionPreviews,
-        commonKnowledgePreviews
-      )
-    )
+        requestContext
+      );
+    }
   }]));
 }
 
@@ -131,22 +178,35 @@ function registerTool(server, tool) {
     inputSchema: schema,
     outputSchema: openObjectSchema(),
     annotations: annotationsFor(definition.name)
-  }, (input) => invokeTool(tool, input));
+  }, (input, extra) => invokeTool(tool, input, extra));
 }
 
 function registerCallHandler(server, tools) {
-  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const tool = tools.get(request.params.name);
-    if (!tool) return errorToolResult(new Error('Unknown tool'));
+    if (!tool) {
+      return errorToolResult(new ApplicationError(
+        ApplicationErrorCode.NOT_FOUND,
+        'Unknown Fuli tool'
+      ));
+    }
     const parsed = await tool.schema.safeParseAsync(request.params.arguments ?? {});
-    if (!parsed.success) return protocolErrorResult('Input validation error');
-    return invokeTool(tool, parsed.data);
+    if (!parsed.success) {
+      return protocolErrorResult(
+        'Input validation error',
+        parsed.error.issues.map(({ path, message }) => ({
+          field: path.length ? path.join('.') : 'arguments',
+          message
+        }))
+      );
+    }
+    return invokeTool(tool, parsed.data, extra);
   });
 }
 
-async function invokeTool(tool, input) {
+async function invokeTool(tool, input, requestContext = null) {
   try {
-    const value = await tool.invoke(input);
+    const value = await tool.invoke(input, requestContext);
     auditLifecycleTool(tool.definition.name);
     const limitBytes = TOOL_RESULT_LIMIT_BYTES[tool.definition.name];
     if (tool.definition.name === 'begin_task_context') {
@@ -167,10 +227,11 @@ async function invokeAgentTool(
   name,
   input,
   projectActionPreviews,
-  commonKnowledgePreviews
+  commonKnowledgePreviews,
+  requestContext = null
 ) {
   if (name === 'preview_personal_project_action') {
-    const result = await callAgentTool(app, name, input);
+    const result = await callAgentTool(app, name, input, requestContext);
     return {
       ...result,
       previewToken: projectActionPreviews.issue(input)
@@ -180,7 +241,7 @@ async function invokeAgentTool(
     projectActionPreviews.consume(input.previewToken, input);
   }
   if (name === 'preview_common_knowledge_promotion') {
-    const result = await callAgentTool(app, name, input);
+    const result = await callAgentTool(app, name, input, requestContext);
     return {
       ...result,
       previewToken: commonKnowledgePreviews.issue(input)
@@ -189,5 +250,5 @@ async function invokeAgentTool(
   if (name === 'apply_common_knowledge_promotion') {
     commonKnowledgePreviews.consume(input.previewToken, input);
   }
-  return callAgentTool(app, name, input);
+  return callAgentTool(app, name, input, requestContext);
 }

package/src/mcp/direct-call.js

@@ -0,0 +1,38 @@
+import { listAgentTools } from '../agent-tools.js';
+import {
+  mcpHostSessionId,
+  nativeCodexThreadId,
+  normalizeAgentSessionInput,
+  normalizeMcpSourceApplication
+} from './session-id.js';
+import { jsonSchemaToZod } from './tool-schema.js';
+
+export async function prepareDirectAgentToolCall({
+  toolName,
+  input,
+  sourceApplication = 'other',
+  env = process.env,
+  clock = () => new Date(),
+  hostSessionId = null
+}) {
+  const definition = listAgentTools().find((item) => item.name === toolName);
+  if (!definition) throw new TypeError('Unknown tool');
+  const parsed = await jsonSchemaToZod(definition.inputSchema).safeParseAsync(input ?? {});
+  if (!parsed.success) throw new TypeError('Input validation error');
+  const source = normalizeMcpSourceApplication(sourceApplication);
+  const nativeThreadId = source === 'codex' ? nativeCodexThreadId(env) : null;
+  const authoritativeHostSessionId = hostSessionId ?? mcpHostSessionId(
+    source === 'codex' ? env : {}
+  );
+  return {
+    definition,
+    input: normalizeAgentSessionInput(
+      toolName,
+      parsed.data,
+      nativeThreadId,
+      authoritativeHostSessionId,
+      clock,
+      source
+    )
+  };
+}

package/src/mcp/instructions.js

@@ -1,9 +1,10 @@
 export const MCP_INSTRUCTIONS = [
-  'Each user task: hook-provided task context via begin_task_context; otherwise before other tools/answer call exactly get_collaboration_preferences(projectPath=cwd taskPrompt=current user request) as fallback; never substitute a project action. Apply all effective_preferences: personal-global everywhere; matched project, authorized inheritable parent. get_user_taste_skill never replaces a user-authored Skill. Resolve deferred_conflict; never guess personalProjectId. Writes use actual payload; final text not compliance.',
-  'Before asking for stable project fact or method inspect task_knowledge_recall. On miss 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 authorized inheritable parent (PART_OF/USES_KNOWLEDGE_FROM); local_only/RELATED_TO never inherit.',
-  'Before saying unknown call search_knowledge_graph; exact IDs for extra projects. RELATED_TO suggests; ask. all_local_confirmed only after consent; rg safe current repo/workspace; Never scan outside it. monitoring/Git MCP; search_connected_knowledge; agent_decide response-only.',
-  'record_decision_trace; failures record_knowledge_feedback. Batch durable confirmed knowledge: capture_session_knowledge; no secrets. checkpoint_task_knowledge: capture_candidates or retain_nothing; record_knowledge_usage.',
-  'Team: coordinate_project_agent_task gives isolated contexts; Fuli never spawns. Host: acquire_runtime_lease, start workers, report activity/executor, release_runtime_lease in finally.',
-  'Non-empty Provider executionSummary: one row/worker: occupation emoji/label, actual executor/sourceApplication, work summary, workerStatus/status. Empty/absent executionSummary: omit. Configured/allowed/available are not evidence.',
-  'Terminal-safe Markdown; never wrap in HTML. A match is a candidate only. If it supports the answer, MUST begin sourceMarker.leadMarkdown and append sourceMarker.markdown; otherwise use noMatchSourceMarker (empty). Keep unchanged.'
+  "Each user task: begin_task_context hook-provided task context; else before tools/answer call exactly get_collaboration_preferences(projectPath=cwd taskPrompt=current user request); never substitute project action. All effective_preferences: personal-global everywhere; matched project, authorized inheritable parent. get_user_taste_skill never replaces user Skill. Resolve deferred_conflict; never guess personalProjectId. Writes=actual payload; final text=not compliance.",
+  "Before asking stable project fact/method: task_knowledge_recall; miss: search_current_project_knowledge with focused action/artifact/target/ID queries, never only the full request. Active child first, then inheritable parent; no local_only/RELATED_TO.",
+  "Before saying unknown: search_knowledge_graph; extra projects=exact IDs. all_local_confirmed only after consent; rg only current repo/workspace. monitoring/Git MCP; search_connected_knowledge; agent_decide response-only.",
+  "record_decision_trace; errors: record_knowledge_feedback. Batch durable confirmed knowledge: capture_session_knowledge; no secrets. checkpoint_task_knowledge: capture_candidates/retain_nothing; record_knowledge_usage.",
+  "coordinate_project_agent_task=isolated context; Fuli never spawns. acquire_runtime_lease; run/report; release_runtime_lease in finally.",
+  "project_management_context: actionable work via authorized manager+board; keep chosen specialist; no excluded projects/extra model. Rename: exact current native session, host rename tool, manual-title protection; receipt after actual client result.",
+  "Task runs until all workerStatus terminal. executionSummary: one table row/worker: occupation emoji/label, actual executor/sourceApplication, work/status/session/link, source-labelled cumulative tokens. Missing=unknown; no invent/estimate/copy totals. Empty: omit. Configured/allowed/available not evidence.",
+  "Terminal-safe Markdown; no HTML. Match=candidate only. If supported: MUST begin sourceMarker.leadMarkdown; append sourceMarker.markdown; otherwise noMatchSourceMarker (empty). Keep unchanged."
 ].join(' ');

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

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+
+// The Provider is the sole source of truth. Hooks commonly use separate MCP
+// processes; a process-local cache cannot prove that a task was checkpointed.
+export class ProviderTaskContextRegistry {
+  constructor(provider, personalSpaceId) {
+    this.provider = provider;
+    this.personalSpaceId = personalSpaceId;
+  }
+
+  async begin(input) {
+    return taskRecord(await this.provider.beginTaskContext({
+      personal_space_id: this.personalSpaceId,
+      personal_project_id: input.personalProjectId ?? null,
+      project_agent_id: input.projectAgentId ?? null,
+      session_id: input.sessionId,
+      source_application: input.sourceApplication ?? 'other',
+      source_session_id: input.sourceSessionId ?? null,
+      token: `fuli-task-${randomUUID()}`,
+      turn_id: input.turnId ?? null,
+      memory_revision: input.memoryRevision ?? null
+    }));
+  }
+
+  async context(token, sourceApplication = 'other') {
+    return taskRecord(await this.provider.getTaskContext(token, {
+      personal_space_id: this.personalSpaceId, source_application: sourceApplication
+    }));
+  }
+
+  prepare(token, checkpoint, sourceApplication = 'other', agentMemory = null) {
+    return this.#write(token, checkpoint, 'prepare', sourceApplication, agentMemory);
+  }
+
+  checkpoint(token, checkpoint, sourceApplication = 'other') {
+    return this.#write(token, checkpoint, 'complete', sourceApplication);
+  }
+
+  verify(sessionId, sourceApplication = 'other') {
+    return this.provider.verifyTaskCheckpoint({
+      personal_space_id: this.personalSpaceId, session_id: sessionId,
+      source_application: sourceApplication
+    });
+  }
+
+  async #write(token, value, phase, sourceApplication, agentMemory = null) {
+    return taskRecord(await this.provider.checkpointTaskContext(token, {
+      personal_space_id: this.personalSpaceId, source_application: sourceApplication,
+      phase, disposition: value.disposition, reason: value.reason,
+      fingerprint: value.fingerprint, capture_status: value.captureStatus ?? null,
+      ...(agentMemory ? { agent_memory: agentMemory } : {})
+    }));
+  }
+}
+
+function taskRecord(value) {
+  if (typeof value?.token !== 'string' || !value?.session_id) {
+    throw new TypeError('Provider did not return a durable task context');
+  }
+  return {
+    token: value.token, sessionId: value.session_id,
+    personalProjectId: value.personal_project_id,
+    projectAgentId: value.project_agent_id,
+    sourceApplication: value.source_application,
+    sourceSessionId: value.source_session_id ?? null,
+    turnId: value.turn_id ?? null,
+    memoryRevision: value.memory_revision,
+    agentMemory: value.agent_memory ?? null,
+    previousCheckpointMissing: Boolean(value.previous_checkpoint_missing),
+    checkpoint: value.checkpoint ? {
+      ...value.checkpoint, captureStatus: value.checkpoint.capture_status
+    } : null
+  };
+}