fuli-context 0.3.0 → 0.5.0

package/src/graphiti/federated-application.js

@@ -23,6 +23,23 @@ import {
   sourceConsoleUrl
 } from './source-marker.js';
 import { resolvePersonalProjectPath } from './project-path-context.js';
+import { TaskContextRegistry } from '../mcp/task-context-registry.js';
+import {
+  agentProjectResolution,
+  beginTaskContext as beginTaskContextWorkflow,
+  checkpointTaskKnowledge as checkpointTaskKnowledgeWorkflow,
+  discoverCommonKnowledgeCandidates as discoverCommonKnowledgeCandidatesWorkflow,
+  providerCommonKnowledgePromotion,
+  recordDecisionTrace as recordDecisionTraceWorkflow,
+  recordKnowledgeFeedback as recordKnowledgeFeedbackWorkflow,
+  searchCurrentProjectKnowledge as searchCurrentProjectKnowledgeWorkflow
+} from './agent-knowledge-workflows.js';
+import {
+  assertPublicKnowledgeEligible,
+  providerConfirmationActor,
+  providerConfirmationBasis,
+  providerEpisode
+} from './knowledge-provider-mapping.js';
 
 export function openFederatedGraphApplication({
   runtimeConfigPath,
@@ -51,7 +68,9 @@ export class FederatedGraphApplication {
     capturePolicyStore = new CapturePolicyStore(),
     agentAccessPolicyStore = new AgentAccessPolicyStore(),
     consoleUrl = sourceConsoleUrl(null),
-    projectPathResolver = resolvePersonalProjectPath
+    projectPathResolver = resolvePersonalProjectPath,
+    taskContextRegistry = new TaskContextRegistry(),
+    providerRequestTimeoutMs = undefined
   } = {}) {
     this.graphiti = true;
     this.config = config;
@@ -59,10 +78,12 @@ export class FederatedGraphApplication {
     this.agentAccessPolicyStore = agentAccessPolicyStore;
     this.consoleUrl = consoleUrl;
     this.projectPathResolver = projectPathResolver;
+    this.taskContextRegistry = taskContextRegistry;
     this.personal = new GraphitiProviderClient({
       baseUrl: config.personal.providerUrl,
       accessToken: config.personal.accessToken,
-      fetchImpl
+      fetchImpl,
+      requestTimeoutMs: providerRequestTimeoutMs
     });
     this.workspaces = new Map(
       config.workspaces.map((workspace) => {
@@ -72,13 +93,31 @@ export class FederatedGraphApplication {
           client: new GraphitiProviderClient({
             baseUrl: url,
             accessToken: workspace.accessToken,
-            fetchImpl
+            fetchImpl,
+            requestTimeoutMs: providerRequestTimeoutMs
           })
         }];
       })
     );
   }
 
+  async beginTaskContext(input) {
+    return beginTaskContextWorkflow(this, input);
+  }
+
+  async checkpointTaskKnowledge(input) {
+    return checkpointTaskKnowledgeWorkflow(this, input);
+  }
+
+  verifyTaskCheckpoint({ sessionId }) {
+    return this.taskContextRegistry.verify(sessionId);
+  }
+
+  async recordDecisionTrace(input) {
+    this.#assertActivePersonalSpace(input.personalSpaceId);
+    return recordDecisionTraceWorkflow(this, input);
+  }
+
   async captureSessionKnowledge(input) {
     const capturePolicy = this.getCapturePolicy();
     if (!capturePolicy.enabled) {
@@ -377,6 +416,36 @@ export class FederatedGraphApplication {
     };
   }
 
+  async searchCurrentProjectKnowledge(input) {
+    const resolution = await this.#resolvePreferenceProject({
+      personalProjectId: null,
+      projectPath: input.projectPath
+    });
+    return searchCurrentProjectKnowledgeWorkflow(this, resolution, input);
+  }
+
+  async discoverCommonKnowledgeCandidates(input) {
+    this.#assertActivePersonalSpace(input.personalSpaceId);
+    return discoverCommonKnowledgeCandidatesWorkflow(this, input);
+  }
+
+  async previewCommonKnowledgePromotion(input) {
+    this.#assertActivePersonalSpace(input.personalSpaceId);
+    assertSafeKnowledgeMutation(input);
+    return this.personal.previewCommonKnowledgePromotion(
+      providerCommonKnowledgePromotion(input)
+    );
+  }
+
+  async applyCommonKnowledgePromotion(input) {
+    this.#assertActivePersonalSpace(input.personalSpaceId);
+    assertSafeKnowledgeMutation(input);
+    return this.personal.applyCommonKnowledgePromotion({
+      ...providerCommonKnowledgePromotion(input),
+      operation_actor: input.operationActor ?? 'agent'
+    });
+  }
+
   async getKnowledgeGraph({
     spaceId,
     providerUrl = null,
@@ -425,6 +494,17 @@ export class FederatedGraphApplication {
     });
   }
 
+  async recordKnowledgeFeedback(input) {
+    this.#assertActivePersonalSpace(input.personalSpaceId);
+    assertSafeKnowledgeMutation({
+      items: input.items.map((item) => ({
+        existenceReason: item.reason,
+        quadrantReason: item.evidenceSummary
+      }))
+    });
+    return recordKnowledgeFeedbackWorkflow(this, input);
+  }
+
   async reviseKnowledgeItem(input) {
     this.#assertActivePersonalSpace(input.personalSpaceId);
     assertSafeKnowledgeMutation(input);
@@ -1039,22 +1119,11 @@ function preferenceConflictPairKey(leftId, rightId) {
   return [leftId, rightId].sort().join('\u0000');
 }
 
-function agentProjectResolution(resolution) {
-  const result = {
-    status: resolution.status,
-    basis: resolution.basis,
-    personal_project_id: resolution.personalProjectId
-  };
-  if (resolution.candidateCount !== undefined) {
-    result.candidate_count = resolution.candidateCount;
-  }
-  return result;
-}
-
 function assertNoCredentials(input) {
   const content = JSON.stringify({
     name: input.name,
     sourceDescription: input.sourceDescription,
+    sourceUri: input.sourceUri,
     sourceExcerpt: input.sourceExcerpt,
     summary: input.summary,
     entities: input.entities,
@@ -1120,6 +1189,7 @@ function assertSafeKnowledgeMutation(input) {
     note: input.note,
     newProjectName: input.newProjectName,
     newProjectPurpose: input.newProjectPurpose,
+    humanConfirmationReason: input.humanConfirmationReason,
     batchItems: input.items?.map((item) => ({
       existenceReason: item.existenceReason,
       quadrantReason: item.quadrantReason
@@ -1133,95 +1203,6 @@ function assertSafeKnowledgeMutation(input) {
   }
 }
 
-function providerEpisode(input) {
-  return {
-    idempotency_key: input.idempotencyKey,
-    session_id: input.sessionId,
-    name: input.name,
-    source_kind: input.sourceKind,
-    source_description: input.sourceDescription,
-    source_application: input.sourceApplication ?? null,
-    source_turn_id: input.sourceTurnId ?? null,
-    source_excerpt: input.sourceExcerpt ?? null,
-    reference_time: input.referenceTime,
-    summary: input.summary ?? '',
-    sensitivity: input.sensitivity ?? 'normal',
-    entities: input.entities.map((entity) => ({
-      key: entity.key,
-      name: entity.name,
-      type: entity.type,
-      summary: entity.summary ?? '',
-      origin_quadrant: entity.originQuadrant ?? 'known_known',
-      current_quadrant: entity.currentQuadrant ?? entity.originQuadrant ?? 'known_known',
-      epistemic_status: entity.epistemicStatus ?? 'confirmed',
-      confirmation_status: entity.confirmationStatus,
-      confirmation_basis: providerConfirmationBasis(entity.confirmationBasis),
-      reasoning_summary: entity.reasoningSummary ?? null,
-      profile_aspect: entity.profileAspect ?? null,
-      inheritance_mode: entity.inheritanceMode ?? 'local_only',
-      inherited_project_ids: entity.inheritedProjectIds ?? [],
-      attributes: entity.attributes ?? {}
-    })),
-    relationships: input.relationships.map((relationship) => ({
-      key: relationship.key,
-      source: relationship.source,
-      target: relationship.target,
-      type: relationship.type,
-      fact: relationship.fact,
-      valid_at: relationship.validAt ?? null,
-      invalid_at: relationship.invalidAt ?? null,
-      supersedes: relationship.supersedes ?? [],
-      confidence: relationship.confidence ?? 1,
-      origin_quadrant: relationship.originQuadrant ?? 'known_known',
-      current_quadrant: relationship.currentQuadrant ??
-        relationship.originQuadrant ?? 'known_known',
-      epistemic_status: relationship.epistemicStatus ?? 'confirmed',
-      confirmation_status: relationship.confirmationStatus,
-      confirmation_basis: providerConfirmationBasis(relationship.confirmationBasis),
-      reasoning_summary: relationship.reasoningSummary ?? null,
-      profile_aspect: relationship.profileAspect ?? null,
-      inheritance_mode: relationship.inheritanceMode ?? 'local_only',
-      inherited_project_ids: relationship.inheritedProjectIds ?? [],
-      attributes: relationship.attributes ?? {}
-    }))
-  };
-}
-
-function assertPublicKnowledgeEligible(episode) {
-  const blocked = [...episode.entities, ...episode.relationships].find((item) =>
-    item.profile_aspect ||
-    item.confirmation_status !== 'confirmed' ||
-    !item.confirmation_basis?.confirmed_by ||
-    !item.confirmation_basis?.confirmed_at ||
-    !['user', 'authoritative_source'].includes(item.confirmation_basis.confirmed_by.kind)
-  );
-  if (blocked) {
-    throw new TypeError(
-      'Only knowledge with an auditable confirmation can enter public review'
-    );
-  }
-}
-
-function providerConfirmationBasis(basis) {
-  if (!basis) return undefined;
-  return {
-    existence_reason: basis.existenceReason,
-    quadrant_reason: basis.quadrantReason,
-    proposed_by: providerConfirmationActor(basis.proposedBy),
-    confirmed_by: providerConfirmationActor(basis.confirmedBy),
-    confirmed_at: basis.confirmedAt ?? null,
-    agent_policy_version: basis.agentPolicyVersion ?? null
-  };
-}
-
-function providerConfirmationActor(actor) {
-  if (!actor) return null;
-  return {
-    kind: actor.kind,
-    label: actor.label ?? null
-  };
-}
-
 function providerProjectProfile(profile) {
   if (!profile || typeof profile !== 'object') throw new TypeError('Project profile is required');
   const assessment = profile.assessment ? sanitizeProjectAssessment(profile.assessment) : null;

package/src/graphiti/knowledge-provider-mapping.js

@@ -0,0 +1,91 @@
+import { onlineSourceUri } from './source-uri.js';
+
+export function providerEpisode(input) {
+  return {
+    idempotency_key: input.idempotencyKey,
+    session_id: input.sessionId,
+    name: input.name,
+    source_kind: input.sourceKind,
+    source_description: input.sourceDescription,
+    source_uri: onlineSourceUri(input.sourceUri),
+    source_application: input.sourceApplication ?? null,
+    source_turn_id: input.sourceTurnId ?? null,
+    source_excerpt: input.sourceExcerpt ?? null,
+    reference_time: input.referenceTime,
+    summary: input.summary ?? '',
+    sensitivity: input.sensitivity ?? 'normal',
+    entities: input.entities.map((entity) => ({
+      key: entity.key,
+      name: entity.name,
+      type: entity.type,
+      summary: entity.summary ?? '',
+      origin_quadrant: entity.originQuadrant ?? 'known_known',
+      current_quadrant: entity.currentQuadrant ?? entity.originQuadrant ?? 'known_known',
+      epistemic_status: entity.epistemicStatus ?? 'confirmed',
+      confirmation_status: entity.confirmationStatus,
+      confirmation_basis: providerConfirmationBasis(entity.confirmationBasis),
+      reasoning_summary: entity.reasoningSummary ?? null,
+      profile_aspect: entity.profileAspect ?? null,
+      inheritance_mode: entity.inheritanceMode ?? 'local_only',
+      inherited_project_ids: entity.inheritedProjectIds ?? [],
+      attributes: entity.attributes ?? {}
+    })),
+    relationships: input.relationships.map((relationship) => ({
+      key: relationship.key,
+      source: relationship.source,
+      target: relationship.target,
+      type: relationship.type,
+      fact: relationship.fact,
+      valid_at: relationship.validAt ?? null,
+      invalid_at: relationship.invalidAt ?? null,
+      supersedes: relationship.supersedes ?? [],
+      confidence: relationship.confidence ?? 1,
+      origin_quadrant: relationship.originQuadrant ?? 'known_known',
+      current_quadrant: relationship.currentQuadrant ??
+        relationship.originQuadrant ?? 'known_known',
+      epistemic_status: relationship.epistemicStatus ?? 'confirmed',
+      confirmation_status: relationship.confirmationStatus,
+      confirmation_basis: providerConfirmationBasis(relationship.confirmationBasis),
+      reasoning_summary: relationship.reasoningSummary ?? null,
+      profile_aspect: relationship.profileAspect ?? null,
+      inheritance_mode: relationship.inheritanceMode ?? 'local_only',
+      inherited_project_ids: relationship.inheritedProjectIds ?? [],
+      attributes: relationship.attributes ?? {}
+    }))
+  };
+}
+
+export function assertPublicKnowledgeEligible(episode) {
+  const blocked = [...episode.entities, ...episode.relationships].find((item) =>
+    item.profile_aspect ||
+    item.confirmation_status !== 'confirmed' ||
+    !item.confirmation_basis?.confirmed_by ||
+    !item.confirmation_basis?.confirmed_at ||
+    !['user', 'authoritative_source'].includes(item.confirmation_basis.confirmed_by.kind)
+  );
+  if (blocked) {
+    throw new TypeError(
+      'Only knowledge with an auditable confirmation can enter public review'
+    );
+  }
+}
+
+export function providerConfirmationBasis(basis) {
+  if (!basis) return undefined;
+  return {
+    existence_reason: basis.existenceReason,
+    quadrant_reason: basis.quadrantReason,
+    proposed_by: providerConfirmationActor(basis.proposedBy),
+    confirmed_by: providerConfirmationActor(basis.confirmedBy),
+    confirmed_at: basis.confirmedAt ?? null,
+    agent_policy_version: basis.agentPolicyVersion ?? null
+  };
+}
+
+export function providerConfirmationActor(actor) {
+  if (!actor) return null;
+  return {
+    kind: actor.kind,
+    label: actor.label ?? null
+  };
+}

package/src/graphiti/provider-client.js

@@ -133,6 +133,11 @@ export class GraphitiProviderClient {
       method: 'POST', body: input
     });
   }
+  recordKnowledgeFeedback(input) {
+    return this.#request('/v1/knowledge/feedback', {
+      method: 'POST', body: input
+    });
+  }
   reviewHumanChange(itemId, input) {
     return this.#request(
       `/v1/knowledge/items/${encodeURIComponent(itemId)}/agent-review`,
@@ -161,6 +166,16 @@ export class GraphitiProviderClient {
       { method: 'POST', body: input }
     );
   }
+  previewCommonKnowledgePromotion(input) {
+    return this.#request('/v1/knowledge/common-promotions/preview', {
+      method: 'POST', body: input
+    });
+  }
+  applyCommonKnowledgePromotion(input) {
+    return this.#request('/v1/knowledge/common-promotions', {
+      method: 'POST', body: input
+    });
+  }
   deferPreferenceConflict(input) {
     return this.#request('/v1/preference-conflicts/defer', {
       method: 'POST', body: input

package/src/graphiti/source-uri.js

@@ -0,0 +1,29 @@
+const SOURCE_URI_ERROR =
+  'Source URI must be an absolute HTTP(S) URI without credentials';
+
+export function onlineSourceUri(value) {
+  if (value === undefined || value === null) return null;
+  if (
+    typeof value !== 'string'
+    || value.length < 1
+    || value.length > 2048
+    || /(?:\s|\p{C})/u.test(value)
+  ) {
+    throw new TypeError(SOURCE_URI_ERROR);
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new TypeError(SOURCE_URI_ERROR);
+  }
+  if (
+    !['http:', 'https:'].includes(parsed.protocol)
+    || !parsed.hostname
+    || parsed.username
+    || parsed.password
+  ) {
+    throw new TypeError(SOURCE_URI_ERROR);
+  }
+  return value;
+}

package/src/http/request-policy.js

@@ -1,3 +1,5 @@
+import { timingSafeEqual } from 'node:crypto';
+
 import { sendJson } from './response.js';
 
 export function localServerAuthority(address) {
@@ -9,18 +11,38 @@ export function localServerAuthority(address) {
 }
 
 export function rejectDisallowedRequest({ request, response, authority }) {
+  return rejectRequestOutsidePolicy({ request, response, authority });
+}
+
+export function rejectRequestOutsidePolicy({
+  request,
+  response,
+  authority,
+  lanAuthorities = [],
+  lanAccessToken = null
+}) {
   const origin = request.headers.origin;
   const fetchSite = request.headers['sec-fetch-site'];
+  const requestAuthority = request.headers.host;
+  const lanRequest = lanAuthorities.includes(requestAuthority);
+  const loopbackRequest = requestAuthority === authority;
   if (
     !authority ||
-    request.headers.host !== authority ||
-    (origin !== undefined && origin !== `http://${authority}`) ||
+    (requestAuthority !== authority && !lanRequest) ||
+    (lanAuthorities.length > 0 && loopbackRequest && !isLoopbackAddress(request.socket?.remoteAddress)) ||
+    (origin !== undefined && origin !== `http://${requestAuthority}`) ||
     (typeof fetchSite === 'string' && fetchSite.toLowerCase() === 'cross-site')
   ) {
     sendJson(response, 403, { error: 'Forbidden' });
     return true;
   }
 
+  if (lanRequest && !hasLanAccess(request.headers.authorization, lanAccessToken)) {
+    response.setHeader('www-authenticate', 'Basic realm="FULI LAN", charset="UTF-8"');
+    sendJson(response, 401, { error: 'LAN access code required' });
+    return true;
+  }
+
   if (requiresJson(request) && !isJson(request.headers['content-type'])) {
     sendJson(response, 415, { error: 'Unsupported media type' });
     return true;
@@ -29,6 +51,19 @@ export function rejectDisallowedRequest({ request, response, authority }) {
   return false;
 }
 
+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) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(authorization), Buffer.from(expected));
+}
+
+function isLoopbackAddress(address) {
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
 function requiresJson(request) {
   if (request.method !== 'POST') return false;
   const pathname = new URL(request.url, 'http://127.0.0.1').pathname;

package/src/local-runtime/lifecycle.js

@@ -20,6 +20,7 @@ export async function startLocalRuntime(input, dependencies = {}) {
     paths: input.paths,
     personalSpaceName: input.personalSpaceName,
     port: input.port,
+    lan: input.lan === true,
     personalOnly: !managesDevelopmentWorkspace,
     buildProviders,
     noStart: false,
@@ -99,7 +100,10 @@ export async function inspectLocalRuntime(input, dependencies = {}) {
     console: {
       status: consoleReady ? 'ready' : processAlive ? 'unverified' : 'stopped',
       url: stateLooksOwned ? state.url : `http://127.0.0.1:${input.port}`,
-      pid: processAlive ? state.pid : null
+      pid: processAlive ? state.pid : null,
+      ...(stateLooksOwned && state.lan === true
+        ? { lan: true, lanUrls: safeLanUrls(state.lanUrls) }
+        : {})
     },
     personal,
     public: {
@@ -237,6 +241,12 @@ function isRuntimeState(state) {
     Number.isInteger(state.pid) && typeof state.url === 'string';
 }
 
+function safeLanUrls(value) {
+  return Array.isArray(value)
+    ? value.filter((url) => typeof url === 'string' && url.startsWith('http://'))
+    : [];
+}
+
 function isProcessAlive(pid) {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }

package/src/mcp/common-knowledge-preview-tokens.js

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+
+import { ApplicationError } from '../app/application-error.js';
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+export function createCommonKnowledgePreviewTokens({
+  now = Date.now,
+  createToken = randomUUID,
+  ttlMs = DEFAULT_TTL_MS
+} = {}) {
+  const previews = new Map();
+
+  return Object.freeze({
+    issue(input) {
+      pruneExpired(previews, now());
+      const token = createToken();
+      previews.set(token, {
+        expiresAt: now() + ttlMs,
+        intent: promotionIntent(input)
+      });
+      return token;
+    },
+
+    consume(token, input) {
+      if (!token) {
+        throw new ApplicationError(
+          'preview_required',
+          'Preview this exact common-knowledge promotion before applying it'
+        );
+      }
+      const preview = previews.get(token);
+      if (!preview || preview.expiresAt <= now()) {
+        previews.delete(token);
+        throw new ApplicationError(
+          'preview_expired',
+          'Common-knowledge preview authorization is missing or expired'
+        );
+      }
+      if (preview.intent !== promotionIntent(input)) {
+        throw new ApplicationError(
+          'preview_mismatch',
+          'Common-knowledge promotion no longer matches its preview'
+        );
+      }
+      previews.delete(token);
+    }
+  });
+}
+
+function promotionIntent(input) {
+  return JSON.stringify({
+    personalSpaceId: input.personalSpaceId,
+    parentProjectId: input.parentProjectId,
+    itemKind: input.itemKind,
+    canonicalItemId: input.canonicalItemId,
+    duplicateItemIds: [...(input.duplicateItemIds ?? [])].sort(),
+    reason: input.reason,
+    humanConfirmationReason: input.humanConfirmationReason
+  });
+}
+
+function pruneExpired(previews, currentTime) {
+  for (const [token, preview] of previews) {
+    if (preview.expiresAt <= currentTime) previews.delete(token);
+  }
+}

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

@@ -5,13 +5,23 @@ import { callAgentTool, listAgentTools } from '../agent-tools.js';
 import { FULI_VERSION } from '../package-metadata.js';
 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 { annotationsFor } from './tool-annotations.js';
-import { errorToolResult, protocolErrorResult, successToolResult } from './tool-result.js';
+import {
+  errorToolResult,
+  hookAdditionalContextToolResult,
+  protocolErrorResult,
+  successToolResult
+} from './tool-result.js';
 import { jsonSchemaToZod, openObjectSchema } from './tool-schema.js';
 
 const TOOL_RESULT_LIMIT_BYTES = Object.freeze({
+  begin_task_context: 16 * 1024,
   get_collaboration_preferences: 16 * 1024,
-  search_knowledge_graph: 32 * 1024
+  search_knowledge_graph: 32 * 1024,
+  search_current_project_knowledge: 64 * 1024,
+  discover_common_knowledge_candidates: 32 * 1024
 });
 
 export function createMcpServer(app) {
@@ -27,6 +37,7 @@ export function createMcpServer(app) {
 }
 
 function createToolMap(app, projectActionPreviews) {
+  const commonKnowledgePreviews = createCommonKnowledgePreviewTokens();
   return new Map(listAgentTools().map((definition) => [definition.name, {
     definition,
     schema: jsonSchemaToZod(definition.inputSchema),
@@ -34,7 +45,8 @@ function createToolMap(app, projectActionPreviews) {
       app,
       definition.name,
       input,
-      projectActionPreviews
+      projectActionPreviews,
+      commonKnowledgePreviews
     )
   }]));
 }
@@ -62,15 +74,29 @@ function registerCallHandler(server, tools) {
 
 async function invokeTool(tool, input) {
   try {
-    return successToolResult(await tool.invoke(input), {
-      limitBytes: TOOL_RESULT_LIMIT_BYTES[tool.definition.name]
-    });
+    const value = await tool.invoke(input);
+    auditLifecycleTool(tool.definition.name);
+    const limitBytes = TOOL_RESULT_LIMIT_BYTES[tool.definition.name];
+    if (tool.definition.name === 'begin_task_context') {
+      return hookAdditionalContextToolResult(value, {
+        hookEventName: 'UserPromptSubmit',
+        label: 'Fuli task context. Apply effective_preferences and use taskContextToken for the final checkpoint.',
+        limitBytes
+      });
+    }
+    return successToolResult(value, { limitBytes });
   } catch (error) {
     return errorToolResult(error);
   }
 }
 
-async function invokeAgentTool(app, name, input, projectActionPreviews) {
+async function invokeAgentTool(
+  app,
+  name,
+  input,
+  projectActionPreviews,
+  commonKnowledgePreviews
+) {
   if (name === 'preview_personal_project_action') {
     const result = await callAgentTool(app, name, input);
     return {
@@ -81,5 +107,15 @@ async function invokeAgentTool(app, name, input, projectActionPreviews) {
   if (name === 'apply_personal_project_action') {
     projectActionPreviews.consume(input.previewToken, input);
   }
+  if (name === 'preview_common_knowledge_promotion') {
+    const result = await callAgentTool(app, name, input);
+    return {
+      ...result,
+      previewToken: commonKnowledgePreviews.issue(input)
+    };
+  }
+  if (name === 'apply_common_knowledge_promotion') {
+    commonKnowledgePreviews.consume(input.previewToken, input);
+  }
   return callAgentTool(app, name, input);
 }