fuli-context 0.7.6 → 0.7.7

package/src/employees/project-selection.js

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { EmployeeError } from './manifest.js';
+
+const projectId = z.string().min(1).max(256);
+const selectionSchema = z.object({
+  personalProjectId: projectId.optional(),
+  personalProjectIds: z.array(projectId).max(500).optional(),
+  replaceAssignments: z.boolean().optional(),
+  expectedAssignmentsVersion: z.string().min(1).max(128).optional(),
+  reactivate: z.boolean().optional(),
+  management: z.unknown().optional(),
+});
+
+export function parseEmployeeProjectSelection(input) {
+  const parsed = selectionSchema.safeParse(input);
+  if (!parsed.success) throw new TypeError('Invalid employee project selection');
+  const value = parsed.data;
+  if ((value.personalProjectId && value.personalProjectIds !== undefined) ||
+    (value.management !== undefined && (value.personalProjectId || value.personalProjectIds !== undefined)) ||
+    (value.replaceAssignments && ((!value.personalProjectIds && value.management === undefined) || !value.expectedAssignmentsVersion)) ||
+    (!value.replaceAssignments && value.expectedAssignmentsVersion !== undefined)) {
+    throw new TypeError('Replacing employee projects requires an explicit project list and its last-read version');
+  }
+  return {
+    projectIds: [...new Set(value.personalProjectIds ?? (value.personalProjectId ? [value.personalProjectId] : []))],
+    replace: value.replaceAssignments === true,
+    expectedVersion: value.expectedAssignmentsVersion,
+  };
+}
+
+export function activeEmployeeAssignments(agent) {
+  return (agent?.assignments ?? []).filter(({ status }) => status === 'active');
+}
+
+export function employeeAssignmentsVersion(agent, policy = null) {
+  const records = activeEmployeeAssignments(agent)
+    .map(({ personalProjectId, assignmentId, revision }) => [personalProjectId, assignmentId, revision ?? 0])
+    .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  return createHash('sha256').update(JSON.stringify(policy ? [records, policy] : records)).digest('hex');
+}
+
+export async function resolveEmployeeProjectSelection(app, spaceId, selection) {
+  const projects = await app.listPersonalProjects({ personalSpaceId: spaceId });
+  const availableIds = new Set(projects.filter((entry) => entry.profile?.lifecycle !== 'archived').map((entry) => entry.project_id));
+  if (selection.projectIds.some((id) => !availableIds.has(id))) {
+    throw new EmployeeError('Project is unavailable; reload and select active FULI projects', 404, 'project_not_found');
+  }
+  return availableIds;
+}

package/src/employees/recruitment.js

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto';
+import { EmployeeError, employeeAgentId, employeeCapability } from './manifest.js';
+import {
+  activeEmployeeAssignments, employeeAssignmentsVersion,
+  parseEmployeeProjectSelection, resolveEmployeeProjectSelection,
+} from './project-selection.js';
+import { managementFor, managementWithoutRevision, parseEmployeeManagement, policyAllowsProject } from './management-policy.js';
+
+export function createEmployeeRecruitment({ app, registry, managementStore }) {
+  const locks = new Map();
+  const spaceId = app.config.personal.spaceId;
+
+  function assertSpace(input) {
+    if (input.personalSpaceId && input.personalSpaceId !== spaceId) {
+      throw new EmployeeError('Employee belongs to another personal space', 403, 'space_mismatch');
+    }
+  }
+
+  async function project(input, required = false) {
+    assertSpace(input);
+    const id = input.personalProjectId;
+    if (!id && !required) return null;
+    if (!id) throw new EmployeeError('Select a project before opening the workbench', 400, 'project_required');
+    const projects = await app.listPersonalProjects({ personalSpaceId: spaceId });
+    const match = projects.find((entry) => entry.project_id === id);
+    if (!match || match.profile?.lifecycle === 'archived') {
+      throw new EmployeeError('Project is unavailable; create or select an active FULI project', 404, 'project_not_found');
+    }
+    return { id: match.project_id, name: match.profile.name, description: match.profile.purpose ?? '' };
+  }
+
+  async function list(input = {}) {
+    assertSpace(input);
+    const [agents, projects] = await Promise.all([
+      app.listProjectAgents({ personalSpaceId: spaceId }),
+      app.listPersonalProjects({ personalSpaceId: spaceId }),
+    ]);
+    return { templates: registry.catalog().map(({ manifest, runtimeStatus }) => {
+      const agent = agents.find(({ agentId }) => agentId === employeeAgentId(manifest.id));
+      const owned = agent?.profile.capabilities.includes(employeeCapability(manifest.id));
+      const stored = managementStore.read(spaceId, manifest.id);
+      const management = managementFor(manifest, owned ? agent : null, stored);
+      const managedProjects = owned && agent.profile.status === 'active' ? projects
+        .filter(entry => entry.profile?.lifecycle !== 'archived' && policyAllowsProject(management, entry.project_id)
+          && (management.mode === 'all' || activeEmployeeAssignments(agent).some(a => a.personalProjectId === entry.project_id)))
+        .map(entry => ({ id: entry.project_id, name: entry.profile.name })) : [];
+      return {
+        ...manifest,
+        runtime: manifest.runtime ? { apiVersion: manifest.runtime.apiVersion } : null,
+        runtimeStatus,
+        agentId: owned ? agent.agentId : null,
+        agentStatus: owned ? agent.profile.status : null,
+        assignmentsVersion: employeeAssignmentsVersion(owned ? agent : null, stored),
+        management, managedProjects,
+        assignmentCount: owned ? activeEmployeeAssignments(agent).length : 0,
+        assignments: owned ? activeEmployeeAssignments(agent) : [],
+        identityConflict: Boolean(agent && !owned)
+      };
+    }) };
+  }
+
+  async function recruit(input) {
+    assertSpace(input);
+    const { manifest } = registry.get(input.templateId);
+    const selection = parseEmployeeProjectSelection(input);
+    const agentId = employeeAgentId(manifest.id);
+    const key = `${spaceId}:${agentId}`;
+    const previous = locks.get(key) ?? Promise.resolve();
+    const operation = previous.catch(() => {}).then(async () => {
+      // Validate the entire snapshot before creating an identity or changing any assignment.
+      const availableIds = await resolveEmployeeProjectSelection(app, spaceId, selection);
+      const agents = await app.listProjectAgents({ personalSpaceId: spaceId });
+      let agent = agents.find((entry) => entry.agentId === agentId);
+      let changed = false;
+      if (agent && !agent.profile.capabilities.includes(employeeCapability(manifest.id))) {
+        throw new EmployeeError('This Agent identifier is already in use; the existing Agent was not modified', 409, 'identity_conflict');
+      }
+      if (agent && agent.profile.status !== 'active' && input.reactivate !== true) {
+        throw new EmployeeError('Confirm reactivation of this employee first', 409, 'reactivation_required');
+      }
+      const active = activeEmployeeAssignments(agent);
+      const stored = managementStore.read(spaceId, manifest.id);
+      const currentPolicy = managementFor(manifest, agent, stored);
+      let desiredPolicy = managementWithoutRevision(currentPolicy);
+      if (input.management !== undefined) {
+        desiredPolicy = parseEmployeeManagement(input.management);
+        if (agent && !selection.replace) throw new TypeError('Updating employee management requires replaceAssignments and its last-read version');
+        const existingProjects = new Set((await app.listPersonalProjects({ personalSpaceId: spaceId })).map(p => p.project_id));
+        if (desiredPolicy.projectIds.some(id => !availableIds.has(id)) || desiredPolicy.excludedProjectIds.some(id => !existingProjects.has(id) && !currentPolicy.excludedProjectIds.includes(id))) {
+          throw new EmployeeError('Project is unavailable; reload the management policy', 404, 'project_not_found');
+        }
+      } else if (input.personalProjectIds !== undefined || input.personalProjectId) {
+        if (currentPolicy.mode === 'all' && agent && !selection.replace) {
+          if (selection.projectIds.some(id => !policyAllowsProject(currentPolicy, id))) {
+            throw new EmployeeError('This project is excluded; update the management policy explicitly', 403, 'project_excluded');
+          }
+        } else {
+          desiredPolicy = { ...desiredPolicy, mode: 'selected', excludedProjectIds: [],
+            projectIds: [...new Set(selection.replace ? selection.projectIds : [...active.map(a => a.personalProjectId), ...selection.projectIds])].sort() };
+        }
+      }
+      const requestedIds = new Set([...availableIds].filter(id => policyAllowsProject(desiredPolicy, id)));
+      const additions = [...requestedIds].filter((id) => !active.some((entry) => entry.personalProjectId === id));
+      // Archived project history stays intact; this control only manages currently available projects.
+      const removals = selection.replace ? active.filter((entry) => availableIds.has(entry.personalProjectId) && !requestedIds.has(entry.personalProjectId)) : [];
+      const policyChanged = JSON.stringify(desiredPolicy) !== JSON.stringify(managementWithoutRevision(currentPolicy));
+      if (selection.replace && (additions.length || removals.length || policyChanged) &&
+        selection.expectedVersion !== employeeAssignmentsVersion(agent, stored)) {
+        throw new EmployeeError('Project assignments changed; reload the selection before saving', 409, 'assignment_scope_conflict');
+      }
+      if (!agent || agent.profile.status !== 'active') {
+        const profile = agent ? { ...agent.profile, status: 'active' } : {
+          name: manifest.name,
+          occupationEmoji: manifest.occupationEmoji,
+          responsibility: `${manifest.role}：${manifest.description}`,
+          agentType: 'durable', status: 'active',
+          capabilities: [...manifest.capabilities, employeeCapability(manifest.id)],
+          workKinds: manifest.workKinds,
+          initialPreferences: manifest.initialPreferences,
+          defaultModelStrategy: { mode: 'adaptive' },
+          executorPolicy: { mode: 'flexible' }
+        };
+        agent = await app.upsertProjectAgent({ personalSpaceId: spaceId, agentId, profile });
+        changed = true;
+      }
+      const endedAssignments = [];
+      try {
+        // Persist the authorization boundary first. Provider writes may fail,
+        // but a newly excluded project must immediately stop reaching the PM.
+        if (policyChanged || !stored) {
+          managementStore.write(spaceId, manifest.id, desiredPolicy, stored?.revision ?? 0);
+          changed = true;
+        }
+        // Revoke first: an interrupted batch must never grant new access before removing exclusions.
+        for (const assignment of removals) {
+          endedAssignments.push(await app.endProjectAgentAssignment({
+            personalSpaceId: spaceId, personalProjectId: assignment.personalProjectId,
+            assignmentId: assignment.assignmentId, expectedRevision: assignment.revision ?? 0,
+            reason: `Update employee ${manifest.id} project selection`,
+          }));
+          changed = true;
+        }
+        for (const personalProjectId of additions) {
+          const history = (agent.assignments ?? []).filter((entry) => entry.personalProjectId === personalProjectId);
+          const generation = history.map((entry) => `${entry.assignmentId}:${entry.revision ?? 0}`).sort();
+          const key = createHash('sha256').update(JSON.stringify([manifest.id, personalProjectId, generation])).digest('hex');
+          await app.createProjectAgentAssignment({
+            personalSpaceId: spaceId, personalProjectId, agentId,
+            idempotencyKey: `employee-assignment:${key}`,
+            responsibility: agent.profile.responsibility,
+            workKinds: agent.profile.workKinds ?? manifest.workKinds,
+            capabilities: agent.profile.capabilities,
+            reason: `Recruit employee template ${manifest.id}@${manifest.version}`,
+          });
+          changed = true;
+        }
+      } catch (error) {
+        if (error instanceof EmployeeError && error.code === 'assignment_scope_conflict') throw error;
+        // Provider assignment writes are individually durable, not a cross-project transaction.
+        throw new EmployeeError('Project selection could not be fully saved; reload actual assignments before retrying', 502, 'assignment_update_incomplete');
+      }
+      agent = (await app.listProjectAgents({ personalSpaceId: spaceId })).find((entry) => entry.agentId === agentId);
+      const assignments = activeEmployeeAssignments(agent);
+      const assignment = selection.projectIds.length === 1
+        ? assignments.find((entry) => entry.personalProjectId === selection.projectIds[0]) ?? null : null;
+      return {
+        templateId: manifest.id, management: managementFor(manifest, agent, managementStore.read(spaceId, manifest.id)),
+        assignmentsVersion: employeeAssignmentsVersion(agent, managementStore.read(spaceId, manifest.id)),
+        assignmentCount: assignments.length, endedAssignmentCount: endedAssignments.length, idempotent: !changed,
+        assignments: structuredClone(assignments), endedAssignments: structuredClone(endedAssignments),
+        assignment: structuredClone(assignment), agent,
+      };
+    });
+    locks.set(key, operation);
+    try { return await operation; }
+    finally { if (locks.get(key) === operation) locks.delete(key); }
+  }
+
+  async function authorize(input) {
+    const selectedProject = await project(input, true);
+    const { manifest } = registry.get(input.templateId);
+    // All-project policy also covers projects without a materialized assignment.
+    const agents = await app.listProjectAgents({ personalSpaceId: spaceId });
+    const agent = agents.find((entry) => entry.agentId === employeeAgentId(manifest.id));
+    const management = managementFor(manifest, agent, managementStore.read(spaceId, manifest.id));
+    if (input.sourceApplication && Array.isArray(agent?.profile.allowedClients) && !agent.profile.allowedClients.includes(input.sourceApplication)) {
+      throw new EmployeeError('This employee is not enabled for the current Agent client', 403, 'assignment_required');
+    }
+    if (!agent || agent.profile.status !== 'active' ||
+      !agent.profile.capabilities.includes(employeeCapability(manifest.id)) ||
+      !policyAllowsProject(management, selectedProject.id) ||
+      (management.mode !== 'all' && !(agent.assignments ?? []).some((entry) => entry.personalProjectId === selectedProject.id && entry.status === 'active'))) {
+      throw new EmployeeError('Recruit this employee into the selected project first', 403, 'assignment_required');
+    }
+    return { personalSpaceId: spaceId, project: selectedProject, agentId: agent.agentId, management };
+  }
+
+  return { list, recruit, authorize };
+}

package/src/employees/service.js

@@ -0,0 +1,83 @@
+import { EmployeeError } from './manifest.js';
+import { createEmployeePackageRegistry, employeeDirectories } from './package-registry.js';
+import { createEmployeeRecruitment } from './recruitment.js';
+import { join } from 'node:path';
+import { EmployeeManagementStore } from './management-policy.js';
+import { employeeTaskEntry } from './task-entry.js';
+
+export function createEmployeeService({ app, runtimeConfigPath, registry: configuredRegistry, managementStore: configuredManagementStore }) {
+  const registry = configuredRegistry ?? createEmployeePackageRegistry(employeeDirectories(runtimeConfigPath));
+  const managementStore = configuredManagementStore ?? new EmployeeManagementStore(runtimeConfigPath
+    ? join(employeeDirectories(runtimeConfigPath).dataDirectory, 'management.sqlite') : ':memory:');
+  const recruitment = createEmployeeRecruitment({ app, registry, managementStore });
+
+  async function resolveInput(input) {
+    if (!input.projectPath) return input;
+    const resolution = await app.listCurrentProjectAgents({ projectPath: input.projectPath });
+    if (!resolution.personal_project_id) {
+      throw new EmployeeError('Register or select this exact FULI project first', 400, 'project_unresolved');
+    }
+    if (input.personalProjectId && input.personalProjectId !== resolution.personal_project_id) {
+      throw new EmployeeError('Project path and project identifier do not match', 403, 'project_mismatch');
+    }
+    return { ...input, personalProjectId: resolution.personal_project_id };
+  }
+
+  async function workspace(input) {
+    const resolved = await resolveInput(input);
+    const context = await recruitment.authorize(resolved);
+    const { manifest, runtimeStatus } = registry.get(resolved.templateId);
+    const basePath = `/employee-workspaces/${encodeURIComponent(manifest.id)}/${encodeURIComponent(context.project.id)}/`;
+    return {
+      ...context, templateId: manifest.id, name: manifest.name, role: manifest.role,
+      runtimeStatus, basePath,
+      workbenchUrl: basePath,
+      agentCardUrl: `${basePath}.well-known/agent-card.json`
+    };
+  }
+
+  async function describeTools(input) {
+    const context = await workspace(input);
+    const runtime = await registry.runtime(context.templateId);
+    return { ...context, tools: await runtime.describeTools() };
+  }
+
+  async function callTool(input) {
+    const context = await workspace(input);
+    const runtime = await registry.runtime(context.templateId);
+    const tools = await runtime.describeTools();
+    const tool = tools.find((entry) => entry.name === input.tool);
+    const { manifest } = registry.get(context.templateId);
+    if (!tool || !manifest.permissions.includes(tool.permission)) {
+      throw new EmployeeError('Employee tool is not available or permitted', 403, 'tool_not_permitted');
+    }
+    const session = input.sourceSessionId ? {
+      sourceApplication: input.sourceApplication ?? 'other', id: input.sourceSessionId,
+      verified: input.sourceSessionVerified === true,
+    } : null;
+    try { return await runtime.callTool(input.tool, input.arguments ?? {}, { ...context, session }); }
+    catch (error) {
+      if (Number.isInteger(error?.status) && error.status >= 400 && error.status < 500) {
+        throw new EmployeeError(error.message, error.status, error.code ?? 'tool_error');
+      }
+      throw error;
+    }
+  }
+
+  return {
+    list: recruitment.list,
+    recruit: async (input) => recruitment.recruit(await resolveInput(input)),
+    workspace, describeTools, callTool,
+    authorize: recruitment.authorize,
+    taskEntry: (input) => employeeTaskEntry({ registry, recruitment, workspace }, input)
+      .catch(() => ({ status: 'unavailable', managers: [], worker_started: false })),
+    async handleHttp(request, response, input) {
+      const context = await workspace(input);
+      const runtime = await registry.runtime(context.templateId);
+      await runtime.handleHttp(request, response, {
+        ...context, origin: input.origin, relativePath: input.relativePath
+      });
+    },
+    async close() { try { await registry.close(); } finally { managementStore.close(); } }
+  };
+}

package/src/employees/task-entry.js

@@ -0,0 +1,39 @@
+// Management is a task-entry capability, not a replacement for the specialist
+// role/executor chosen by FULI. Never persist the user's prompt or start a model.
+export async function employeeTaskEntry({ registry, recruitment, workspace }, input) {
+  if (!input.personalProjectId) return { status: 'project_unresolved', managers: [], worker_started: false };
+  const managers = [];
+  let unavailable = false;
+  for (const { manifest, runtimeStatus } of registry.catalog()) {
+    if (!manifest.taskEntry) continue;
+    try {
+      const context = await recruitment.authorize({ templateId: manifest.id, personalProjectId: input.personalProjectId, sourceApplication: input.sourceApplication });
+      if (runtimeStatus !== 'ready') { unavailable = true; continue; }
+      const resolved = await workspace({ templateId: manifest.id, personalProjectId: input.personalProjectId, sourceApplication: input.sourceApplication });
+      const runtime = await registry.runtime(manifest.id);
+      const definition = (await runtime.describeTools()).find(tool => tool.name === manifest.taskEntry.boardTool);
+      if (!definition || definition.permission !== 'board.read' || !manifest.permissions.includes('board.read')) {
+        unavailable = true; continue;
+      }
+      const board = await runtime.callTool(manifest.taskEntry.boardTool, { limit: 8 }, resolved);
+      managers.push({
+        template_id: manifest.id, agent_id: context.agentId, name: manifest.name,
+        personal_project_id: context.project.id, scope_mode: context.management.mode,
+        title_mode: context.management.titleMode, title_style: context.management.titleStyle,
+        board: { version: board.version, total: board.total, truncated: board.truncated,
+          items: (board.items ?? []).slice(0, 8).map(item => ({
+            id: item.id, title: item.title, status: item.status, priority: item.priority,
+            workType: item.workType, updatedAt: item.updatedAt,
+          })) },
+        session: { sourceApplication: input.sourceApplication ?? 'other', sessionId: input.sourceSessionId ?? input.sessionId ?? null },
+        tools: { discover: 'list_employee_tools', call: 'call_employee_tool',
+          read_board: manifest.taskEntry.boardTool, prepare_title: manifest.taskEntry.titleTool ?? null },
+        guidance: 'Route actionable work in this project through this manager: match existing board items, or create a concise task for new work. Keep conversation-only questions out of the backlog. Update linked items as evidence arrives; Agent completion goes to review, never human-confirmed done. Before creating or editing, discover the installed tool schemas and preserve versions/idempotency. If title_mode is auto or suggest, prepare a title from only this session’s linked work item IDs. Auto applies only when the current host exposes a native session rename capability and the exact target session is known: execute the returned action in that host, then report its actual result. Never edit client databases or transcripts, invent an execution receipt, rename another session, or override a locked/manual title. Do not start an additional model solely for this entry.'
+      });
+    } catch (error) {
+      // Excluded/unassigned/inactive projects never reach the plugin runtime.
+      if (!['assignment_required', 'project_not_found'].includes(error?.code)) unavailable = true;
+    }
+  }
+  return { status: unavailable ? 'degraded' : managers.length ? 'ready' : 'not_managed', managers, worker_started: false };
+}

package/src/graphiti/agent-knowledge-workflows.js

@@ -1,5 +1,8 @@
 import { createHash } from 'node:crypto';
 
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+import { agentMemoryRecord, prepareProjectAgentMemory } from './project-agent-memory.js';
+
 import { onlineSourceUri } from './source-uri.js';
 import {
   relatedProjectGuidance,
@@ -8,28 +11,58 @@ import {
 
 export async function beginTaskContext(application, {
   sessionId,
+  turnId = null,
   projectPath,
-  taskPrompt = null
+  personalProjectId = null,
+  taskPrompt = null,
+  sourceApplication = 'other',
+  sourceSessionId = null,
+  projectAgentId = null,
+  workKind = null,
+  requiredCapabilities = []
 }) {
+  const continuationToken = /^FULI_CHECKPOINT_REQUIRED: (fuli-task-[a-zA-Z0-9-]{8,128})\b/.exec(taskPrompt ?? '')?.[1];
+  const resumed = continuationToken
+    ? await application.taskContextRegistry.context(continuationToken, sourceApplication) : null;
+  if (resumed && resumed.sessionId !== sessionId) {
+    throw validationError('Checkpoint continuation belongs to another host session');
+  }
   const preferences = await application.getCollaborationPreferences({
+    personalProjectId,
     projectPath,
+    sessionId,
+    turnId,
     taskPrompt,
+    projectAgentId: resumed?.projectAgentId ?? projectAgentId,
+    sourceApplication,
+    sourceSessionId,
+    workKind,
+    requiredCapabilities,
     agentInvocation: true,
     agentToolName: 'begin_task_context'
   });
-  const task = application.taskContextRegistry.begin({
+  if (resumed && resumed.personalProjectId !== preferences.context.personal_project_id) {
+    throw validationError('Checkpoint continuation belongs to another project');
+  }
+  const task = resumed ?? await application.taskContextRegistry.begin({
     sessionId,
-    personalProjectId: preferences.context.personal_project_id
+    turnId,
+    personalProjectId: preferences.context.personal_project_id,
+    projectAgentId: preferences.context.project_agent_id,
+    sourceApplication,
+    sourceSessionId,
+    memoryRevision: preferences.project_agent_context?.memory?.revision ?? null
   });
   return {
     taskContextToken: task.token,
     task_context_token: task.token,
-    checkpoint_required: true,
+    checkpoint_required: task.checkpoint?.phase !== 'complete',
+    resumed_checkpoint: Boolean(resumed),
     previous_checkpoint_missing: task.previousCheckpointMissing,
     ...preferences,
     task_guidance: {
       retrieval: 'Inspect task_knowledge_recall before asking for a stable project fact or method again. On a miss, use search_current_project_knowledge with focused action, artifact, target-system, or identifier queries; never use the full conversational request as the only query.',
-      checkpoint: 'Before finishing, call checkpoint_task_knowledge with capture_candidates or retain_nothing.'
+      checkpoint: 'Before finishing, call checkpoint_task_knowledge with capture_candidates or retain_nothing. When durable role context changed, include agentMemory with the loaded revision and a bounded merged summary, decisions, open threads and next actions. Do not overwrite from truncated context or store raw transcripts.'
     }
   };
 }
@@ -38,43 +71,120 @@ export async function checkpointTaskKnowledge(application, {
   taskContextToken,
   disposition,
   reason,
-  capture = null
+  capture = null,
+  agentMemory = null,
+  sourceApplication = 'other',
+  personalProjectId = null,
+  remoteSessionId = null
 }) {
   if (!['capture_candidates', 'retain_nothing'].includes(disposition)) {
-    throw new TypeError('Unknown task knowledge checkpoint disposition');
+    throw validationError('Unknown task knowledge checkpoint disposition');
+  }
+  const task = await application.taskContextRegistry.context(taskContextToken, sourceApplication);
+  if (personalProjectId && task.personalProjectId !== personalProjectId) {
+    throw validationError('Task checkpoint belongs to another project');
+  }
+  if (remoteSessionId && task.sessionId !== remoteSessionId) {
+    throw validationError('Task checkpoint belongs to another remote session');
   }
-  const task = application.taskContextRegistry.context(taskContextToken);
-
-  let captureResult = null;
   if (disposition === 'capture_candidates') {
     if (!capture) {
-      throw new TypeError('capture_candidates requires a bounded capture payload');
+      throw validationError('capture_candidates requires a bounded capture payload');
+    }
+  } else if (capture) {
+    throw validationError('retain_nothing cannot include a capture payload');
+  }
+  const fingerprint = createHash('sha256').update(JSON.stringify(
+    canonicalCheckpoint({ disposition, reason, capture, agentMemory })
+  )).digest('hex');
+  if (task.checkpoint && task.checkpoint.fingerprint !== fingerprint) {
+    throw validationError(
+      'Task checkpoint already has different input; resume the original review or begin a new task context'
+    );
+  }
+  if (task.checkpoint?.phase === 'complete') {
+    return { status: 'checkpointed', disposition, reason,
+      personal_project_id: task.personalProjectId, project_agent_id: task.projectAgentId,
+      replayed: true, capture_status: task.checkpoint.captureStatus };
+  }
+  const captureInput = capture ? {
+    ...capture,
+    targetKind: 'personal',
+    spaceId: application.config.personal.spaceId,
+    personalProjectId: task.personalProjectId,
+    projectAgentId: task.projectAgentId ?? null,
+    sessionId: task.sessionId,
+    sourceApplication,
+    idempotencyKey: `${task.token}:knowledge`
+  } : null;
+  // Local validation has no side effects. Reject correctable input before
+  // binding an immutable checkpoint or advancing the Agent's memory revision.
+  if (captureInput) application.validateCaptureSessionKnowledge(captureInput);
+  let memoryResult = null;
+  let memoryRequest = null;
+  if (agentMemory) {
+    if (!task.projectAgentId || !task.personalProjectId) {
+      throw validationError('Task has no durable project Agent; do not guess a memory target');
     }
-    captureResult = await application.captureSessionKnowledge({
-      targetKind: 'personal',
-      spaceId: application.config.personal.spaceId,
+    const prepared = await prepareProjectAgentMemory(application, {
+      personalSpaceId: application.config.personal.spaceId,
       personalProjectId: task.personalProjectId,
-      sessionId: task.sessionId,
-      ...capture
+      agentId: task.projectAgentId,
+      expectedRevision: agentMemory.expectedRevision,
+      idempotencyKey: `${task.token}:memory`,
+      memory: agentMemory.memory, sourceApplication,
+      // The logical client session survives independent lifecycle-hook MCP
+      // processes; their host session ids do not. The Provider persists this
+      // stable task session as the memory checkpoint provenance.
+      sourceSessionId: task.sessionId
     });
-  } else if (capture) {
-    throw new TypeError('retain_nothing cannot include a capture payload');
+    if (prepared.status === 'capture_disabled') memoryResult = prepared;
+    else memoryRequest = { expected_revision: prepared.request.expected_revision,
+      memory: prepared.request.memory };
   }
-
-  application.taskContextRegistry.checkpoint(taskContextToken, {
-    disposition,
-    reason,
-    captureStatus: captureResult?.status ?? null
-  });
+  const checkpoint = { disposition, reason, fingerprint, captureStatus: null };
+  const preparedTask = await application.taskContextRegistry.prepare(
+    taskContextToken, checkpoint, sourceApplication, memoryRequest
+  );
+  if (memoryRequest) {
+    if (!preparedTask.agentMemory) {
+      throw new TypeError('Provider did not confirm atomic Agent memory preparation');
+    }
+    memoryResult = { status: 'checkpointed', ...agentMemoryRecord(preparedTask.agentMemory) };
+  }
+  const captureResult = captureInput
+    ? await application.captureSessionKnowledge(captureInput) : null;
+  await application.taskContextRegistry.checkpoint(taskContextToken, {
+    ...checkpoint, captureStatus: captureResult?.status ?? null
+  }, sourceApplication);
   return {
     status: 'checkpointed',
     disposition,
     reason,
     personal_project_id: task.personalProjectId,
-    capture: captureResult
+    project_agent_id: task.projectAgentId ?? null,
+    capture: captureResult,
+    agent_memory: memoryResult ? {
+      status: memoryResult.status, agentId: memoryResult.agentId,
+      checkpointId: memoryResult.checkpointId, revision: memoryResult.revision,
+      sourceApplication: memoryResult.sourceApplication,
+      sourceSessionId: memoryResult.sourceSessionId, createdAt: memoryResult.createdAt
+    } : null
   };
 }
 
+function canonicalCheckpoint(value) {
+  if (Array.isArray(value)) return value.map(canonicalCheckpoint);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [
+    key, canonicalCheckpoint(value[key])
+  ]));
+}
+
+function validationError(message) {
+  return new ApplicationError(ApplicationErrorCode.VALIDATION, message);
+}
+
 export async function recordDecisionTrace(application, input) {
   const trace = decisionTraceKnowledge(input);
   return application.captureSessionKnowledge({