fuli-context 0.7.6 → 0.7.8

package/src/graphiti/provider-client.js

@@ -1,4 +1,5 @@
 import { ApplicationError } from '../app/application-error.js';
+import { activeAgentRequestSignal } from '../app/agent-request-context.js';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const MAX_REQUEST_TIMEOUT_MS = 2_147_483_647;
@@ -102,6 +103,35 @@ export class GraphitiProviderClient {
       `/v1/project-agents/${encodeURIComponent(agentId)}?${query}`
     );
   }
+  getProjectAgentMemory({ personalSpaceId, personalProjectId, agentId, limit = 1 }) {
+    const query = new URLSearchParams({
+      personal_space_id: personalSpaceId, personal_project_id: personalProjectId,
+      limit: String(limit)
+    });
+    return this.#request(`/v1/project-agents/${encodeURIComponent(agentId)}/memory?${query}`);
+  }
+  writeProjectAgentMemory(input) {
+    return this.#request(`/v1/project-agents/${encodeURIComponent(input.agent_id)}/memory`, {
+      method: 'PUT', body: input
+    });
+  }
+  resolveProjectAgentContext(input) {
+    return this.#request('/v1/project-agent-context/resolve', { method: 'POST', body: input });
+  }
+  beginTaskContext(input) {
+    return this.#request('/v1/task-contexts', { method: 'PUT', body: input });
+  }
+  getTaskContext(token, query) {
+    return this.#request(`/v1/task-contexts/${encodeURIComponent(token)}?${new URLSearchParams(query)}`);
+  }
+  checkpointTaskContext(token, input) {
+    return this.#request(`/v1/task-contexts/${encodeURIComponent(token)}/checkpoint`, {
+      method: 'PUT', body: input
+    });
+  }
+  verifyTaskCheckpoint(query) {
+    return this.#request(`/v1/task-context-sessions/checkpoint?${new URLSearchParams(query)}`);
+  }
   deleteProjectAgent(personalSpaceId, agentId, reason = 'archived by user') {
     const query = new URLSearchParams({
       personal_space_id: personalSpaceId,
@@ -169,8 +199,12 @@ export class GraphitiProviderClient {
     if (limit !== null && limit !== undefined) query.set('limit', String(limit));
     return this.#request(`/v1/project-agent-tasks?${query}`);
   }
-  viewProjectAgentTask(personalSpaceId, taskId, { includeEvents = true } = {}) {
+  viewProjectAgentTask(personalSpaceId, taskId, {
+    personalProjectId = null,
+    includeEvents = true
+  } = {}) {
     const query = new URLSearchParams({ personal_space_id: personalSpaceId });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
     query.set('include_events', String(includeEvents));
     return this.#request(
       `/v1/project-agent-tasks/${encodeURIComponent(taskId)}?${query}`
@@ -186,6 +220,7 @@ export class GraphitiProviderClient {
   }
   listProjectAgentActivity({
     personalSpaceId,
+    personalProjectId = null,
     agentId,
     fromDate = null,
     toDate = null
@@ -196,6 +231,7 @@ export class GraphitiProviderClient {
       from: fromDate ?? toDate ?? today,
       to: toDate ?? fromDate ?? today
     });
+    if (personalProjectId) query.set('personal_project_id', personalProjectId);
     return this.#request(
       `/v1/project-agents/${encodeURIComponent(agentId)}/activity?${query}`
     );
@@ -634,7 +670,10 @@ export class GraphitiProviderClient {
       timedOut = true;
       controller.abort(new Error('Graphiti provider request timed out'));
     }, this.requestTimeoutMs);
-    const { signal } = controller;
+    const callerSignal = activeAgentRequestSignal();
+    const signal = callerSignal
+      ? AbortSignal.any([controller.signal, callerSignal])
+      : controller.signal;
     let response;
     let payload;
     try {
@@ -646,6 +685,10 @@ export class GraphitiProviderClient {
       });
       payload = await parseResponse(response);
     } catch (error) {
+      if (error instanceof ProviderRequestError) throw error;
+      if (!timedOut && callerSignal?.aborted) {
+        throw callerSignal.reason ?? new DOMException('Aborted', 'AbortError');
+      }
       const diagnostic = {
         category: timedOut ? 'provider_timeout' : 'provider_unavailable',
         status: timedOut ? 504 : 0,
@@ -684,9 +727,28 @@ export class GraphitiProviderClient {
 
 async function parseResponse(response) {
   const type = response.headers.get('content-type') ?? '';
-  if (type.includes('application/json')) return response.json();
   const text = await response.text();
-  return text ? { detail: text } : null;
+  if (!type.includes('application/json')) {
+    if (!response.ok) return text ? { detail: text } : null;
+    throw invalidResponse(
+      text ? 'Graphiti provider returned a non-JSON response.'
+        : 'Graphiti provider returned an empty response.'
+    );
+  }
+  if (!text.trim()) {
+    if (!response.ok) return null;
+    throw invalidResponse('Graphiti provider returned an empty response.');
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (!response.ok) return null;
+    throw invalidResponse('Graphiti provider returned invalid JSON.');
+  }
+}
+
+function invalidResponse(message) {
+  return new ProviderRequestError(message, { code: 'provider_invalid_response' });
 }
 
 function providerErrorDiagnostic(status, payload) {

package/src/http/api-router.js

@@ -1,6 +1,7 @@
 import { readJson, sendJson } from './response.js';
 import { handleExternalKnowledgeApiRequest } from './external-knowledge-api-router.js';
 import { handleGraphApiRequest } from './graph-api-router.js';
+import { handleEmployeeApiRequest } from './employee-api-router.js';
 
 export async function handleApiRequest({
   request,
@@ -36,13 +37,24 @@ export async function handleApiRequest({
     return true;
   }
 
+  if (system && url.pathname === '/api/system/version' && request.method === 'GET') {
+    sendJson(response, 200, await system.versionStatus());
+    return true;
+  }
+
   if (system && url.pathname === '/api/system/runtime' && request.method === 'GET') {
     sendJson(response, 200, system.runtimeStatus());
     return true;
   }
 
   if (system && url.pathname === '/api/system/runtime/leases' && request.method === 'POST') {
-    sendJson(response, 201, await system.acquireRuntimeLease(await readJson(request)));
+    const lease = await system.acquireRuntimeLease(await readJson(request));
+    if (response.destroyed) {
+      // Startup can outlive the caller's timeout. No recipient can now renew/release this handle.
+      if (lease.leaseId) system.releaseRuntimeLease(lease.leaseId);
+      return true;
+    }
+    sendJson(response, 201, lease);
     return true;
   }
 
@@ -51,7 +63,7 @@ export async function handleApiRequest({
     sendJson(
       response,
       200,
-      system.refreshRuntimeLease(decodeURIComponent(runtimeLease[1]))
+      system.refreshRuntimeLease(decodeRuntimeLeaseId(runtimeLease[1]))
     );
     return true;
   }
@@ -59,7 +71,7 @@ export async function handleApiRequest({
     sendJson(
       response,
       200,
-      system.releaseRuntimeLease(decodeURIComponent(runtimeLease[1]))
+      system.releaseRuntimeLease(decodeRuntimeLeaseId(runtimeLease[1]))
     );
     return true;
   }
@@ -76,8 +88,12 @@ export async function handleApiRequest({
     : await externalRequest();
   if (handledExternal) return true;
 
-  const graphRequest = () => handleGraphApiRequest({ request, response, url, app });
-  if (system?.withGraphRuntimeLease && url.pathname.startsWith('/api/')) {
+  const graphRequest = async () =>
+    await handleEmployeeApiRequest({ request, response, url, app }) ||
+    await handleGraphApiRequest({ request, response, url, app });
+  if (system?.withGraphRuntimeLease && (
+    url.pathname.startsWith('/api/') || url.pathname.startsWith('/employee-workspaces/')
+  )) {
     return system.withGraphRuntimeLease(
       `http:${request.method}:${url.pathname}`,
       graphRequest
@@ -86,6 +102,15 @@ export async function handleApiRequest({
   return graphRequest();
 }
 
+function decodeRuntimeLeaseId(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    if (error instanceof URIError) throw new TypeError('Runtime lease ID is invalid');
+    throw error;
+  }
+}
+
 function externalRequestNeedsGraph(pathname, method) {
   if (pathname === '/api/connected-knowledge/search' && method === 'POST') return true;
   if (pathname === '/api/external-knowledge/bindings' && method === 'POST') return true;

package/src/http/employee-api-router.js

@@ -0,0 +1,64 @@
+import { EmployeeError } from '../employees/manifest.js';
+import { readJson, sendJson } from './response.js';
+
+export async function handleEmployeeApiRequest({ request, response, url, app }) {
+  const employees = app.employees;
+  const apiPath = url.pathname.match(/^\/api\/employee-templates(?:\/([^/]+)\/(recruit|workspace|tools|call))?$/);
+  const workspacePath = url.pathname.match(/^\/employee-workspaces\/([^/]+)\/([^/]+)(\/.*)?$/);
+  if (!apiPath && !workspacePath) return false;
+  if (!employees) throw new EmployeeError('Employee runtime is unavailable', 503, 'runtime_unavailable');
+  if (workspacePath) {
+    const templateId = decodeEmployeePathSegment(workspacePath[1]);
+    const personalProjectId = decodeEmployeePathSegment(workspacePath[2]);
+    if (!workspacePath[3]) {
+      response.writeHead(308, { location: `${url.pathname}/${url.search}` });
+      response.end();
+      return true;
+    }
+    await employees.handleHttp(request, response, {
+      templateId,
+      personalProjectId,
+      relativePath: `${workspacePath[3]}${url.search}`,
+      origin: `http://${request.headers.host}`
+    });
+    return true;
+  }
+  const input = {
+    templateId: apiPath[1] ? decodeEmployeePathSegment(apiPath[1]) : undefined,
+    personalSpaceId: url.searchParams.get('personalSpaceId'),
+    personalProjectId: url.searchParams.get('personalProjectId')
+  };
+  let result;
+  if (!apiPath[1] && request.method === 'GET') result = await employees.list(input);
+  else if (apiPath[2] === 'recruit' && request.method === 'POST') {
+    const body = await readJson(request);
+    if (!body || typeof body !== 'object' || Array.isArray(body) ||
+      Object.keys(body).some((key) => !['personalSpaceId', 'personalProjectId', 'personalProjectIds', 'replaceAssignments', 'expectedAssignmentsVersion', 'reactivate', 'management'].includes(key)) ||
+      (body.reactivate !== undefined && typeof body.reactivate !== 'boolean')) {
+      throw new TypeError('Invalid employee recruitment request');
+    }
+    result = await employees.recruit({ ...body, templateId: input.templateId });
+  } else if (apiPath[2] === 'workspace' && request.method === 'GET') result = await employees.workspace(input);
+  else if (apiPath[2] === 'tools' && request.method === 'GET') result = await employees.describeTools(input);
+  else if (apiPath[2] === 'call' && request.method === 'POST') {
+    const body = await readJson(request);
+    if (!body || typeof body !== 'object' || Array.isArray(body) ||
+      Object.keys(body).some((key) => !['personalSpaceId', 'personalProjectId', 'tool', 'arguments'].includes(key)) ||
+      typeof body.tool !== 'string') throw new TypeError('Invalid employee tool call');
+    result = await employees.callTool({ ...body, templateId: input.templateId });
+  } else {
+    sendJson(response, 405, { error: 'Method not allowed' });
+    return true;
+  }
+  sendJson(response, 200, result);
+  return true;
+}
+
+function decodeEmployeePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    if (error instanceof URIError) throw new TypeError('Invalid employee path encoding');
+    throw error;
+  }
+}

package/src/http/error-mapping.js

@@ -4,6 +4,7 @@ import {
 } from '../app/application-error.js';
 import { JsonBodyTooLargeError } from './response.js';
 import { ProviderRequestError } from '../graphiti/provider-client.js';
+import { EmployeeError } from '../employees/manifest.js';
 
 const BAD_REQUEST_CODES = new Set([
   ApplicationErrorCode.NOT_FOUND,
@@ -11,6 +12,9 @@ const BAD_REQUEST_CODES = new Set([
 ]);
 
 export function mapHttpError(error) {
+  if (error instanceof EmployeeError) {
+    return { status: error.status, body: { error: error.message, code: error.code } };
+  }
   if (error instanceof JsonBodyTooLargeError) {
     return { status: 413, body: { error: 'Request body too large' } };
   }

package/src/http/graph-api-router.js

@@ -265,6 +265,7 @@ export async function handleGraphApiRequest({
   if (projectAgentTaskPath && request.method === 'GET') {
     sendJson(response, 200, await app.viewProjectAgentTask({
       personalSpaceId: url.searchParams.get('personalSpaceId'),
+      personalProjectId: url.searchParams.get('personalProjectId'),
       taskId: decodeURIComponent(projectAgentTaskPath[1]),
       includeEvents: url.searchParams.get('includeEvents') !== 'false'
     }));
@@ -273,6 +274,7 @@ export async function handleGraphApiRequest({
   if (url.pathname === '/api/project-agent-activity' && request.method === 'GET') {
     sendJson(response, 200, await app.viewProjectAgentActivity({
       personalSpaceId: url.searchParams.get('personalSpaceId'),
+      personalProjectId: url.searchParams.get('personalProjectId'),
       agentId: url.searchParams.get('agentId'),
       fromDate: url.searchParams.get('fromDate'),
       toDate: url.searchParams.get('toDate')

package/src/http/request-policy.js

@@ -54,10 +54,13 @@ export function rejectRequestOutsidePolicy({
 function hasLanAccess(authorization, accessToken) {
   if (typeof accessToken !== 'string' || !accessToken) return false;
   const expected = `Basic ${Buffer.from(`fuli:${accessToken}`).toString('base64')}`;
-  if (typeof authorization !== 'string' || authorization.length !== expected.length) {
+  if (typeof authorization !== 'string') {
     return false;
   }
-  return timingSafeEqual(Buffer.from(authorization), Buffer.from(expected));
+  const providedBytes = Buffer.from(authorization);
+  const expectedBytes = Buffer.from(expected);
+  return providedBytes.length === expectedBytes.length &&
+    timingSafeEqual(providedBytes, expectedBytes);
 }
 
 function isLoopbackAddress(address) {
@@ -67,7 +70,7 @@ function isLoopbackAddress(address) {
 function requiresJson(request) {
   if (!['PATCH', 'POST', 'PUT'].includes(request.method)) return false;
   const pathname = new URL(request.url, 'http://127.0.0.1').pathname;
-  return pathname.startsWith('/api/');
+  return pathname.startsWith('/api/') || pathname.startsWith('/employee-workspaces/');
 }
 
 function isJson(contentType) {

package/src/http/static-handler.js

@@ -38,7 +38,7 @@ export function serveStatic(pathname, response) {
   const pathFromRoot = relative(WEB_ROOT, requestedFile);
   if (pathFromRoot === '..' || pathFromRoot.startsWith(`..${sep}`) ||
       isAbsolute(pathFromRoot)) {
-    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
     response.end('Not found');
     return;
   }
@@ -49,13 +49,14 @@ export function serveStatic(pathname, response) {
       ? join(WEB_ROOT, 'index.html')
       : null;
   if (!filePath || !existsSync(filePath)) {
-    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
     response.end('Not found');
     return;
   }
 
   response.writeHead(200, {
-    'content-type': MIME_TYPES[extname(filePath)] ?? 'application/octet-stream'
+    'content-type': MIME_TYPES[extname(filePath)] ?? 'application/octet-stream',
+    ...(extname(filePath) === '.html' ? { 'cache-control': 'no-cache' } : {})
   });
   response.end(readFileSync(filePath));
 }

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(' ');