@modelprofile.com/flexharness 10.24.0 → 11.0.0

package/ts/classes.flexharness.projects.ts

@@ -0,0 +1,1006 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessNotFoundError,
+  FlexHarnessStoreConflictError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  type IFlexCreateProjectTaskInput,
+  type IFlexProjectGoalResult,
+  type IFlexProjectManagementSessionContext,
+  type IFlexProjectManagementSnapshot,
+  type IFlexProjectManagementTombstone,
+  type IFlexProjectManagementWriteContext,
+  type IFlexProjectScratchpadResult,
+  type IFlexProjectStateResult,
+  type IFlexProjectTask,
+  type IFlexProjectTaskResult,
+  type IFlexProjectTasksResult,
+  type IFlexSession,
+  type IFlexSessionTombstone,
+  type IFlexUpdateProjectTaskInput,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import {
+  assertFlexProjectManagementRecord,
+  assertFlexProjectManagementSnapshot,
+  createEmptyFlexProjectManagementSnapshot,
+} from './utils.projectmanagement.js';
+import type { INormalizedProjectManagementTools } from './utils.harnessoptions.js';
+import { maxTransferIdentifierBytes, publicSnapshot } from './utils.transfer.js';
+import {
+  validateCreateProjectTaskInput,
+  validateProjectTaskId,
+  validateUpdateProjectTaskInput,
+  validateUtf8String,
+} from './utils.validation.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  TProjectTaskToolInput,
+  TProjectGoalToolInput,
+  TProjectScratchpadToolInput,
+} from './interfaces.flexharness.js';
+import { queueOperation, requireSessionGeneration, sha256Hex } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+const maxProjectManagementTombstoneConflicts = 8;
+
+/** The project tasks, goal and scratchpad that a session tree shares, and their agent tools. */
+export class FlexHarnessProjectManagement<TScope> {
+  public readonly projectManagementQueues = new Map<string, Promise<void>>();
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async getProjectState(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectStateResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectStateResult(snapshot);
+  }
+
+  public async listProjectTasks(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectTasksResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectTasksResult(snapshot, snapshot.tasks);
+  }
+
+  public async createProjectTask(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexCreateProjectTaskInput,
+  ): Promise<IFlexProjectTaskResult> {
+    validateCreateProjectTaskInput(input);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.createProjectTaskInState(
+      state,
+      stored,
+      input,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async updateProjectTask(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexUpdateProjectTaskInput,
+  ): Promise<IFlexProjectTaskResult> {
+    validateUpdateProjectTaskInput(input);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.updateProjectTaskInState(
+      state,
+      stored,
+      input,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async deleteProjectTask(
+    scopeId: string,
+    sessionId: string,
+    taskId: string,
+  ): Promise<IFlexProjectTaskResult> {
+    validateProjectTaskId(taskId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.deleteProjectTaskInState(
+      state,
+      stored,
+      taskId,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectTasks(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectTasksResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.clearProjectTasksInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async getProjectGoal(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectGoalResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectGoalResult(snapshot);
+  }
+
+  public async setProjectGoal(
+    scopeId: string,
+    sessionId: string,
+    goal: string,
+  ): Promise<IFlexProjectGoalResult> {
+    validateUtf8String(
+      goal,
+      'project goal',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+      true,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.setProjectGoalInState(
+      state,
+      stored,
+      goal,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectGoal(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectGoalResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.clearProjectGoalInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async getProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectScratchpadResult(snapshot);
+  }
+
+  public async setProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+    content: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    validateUtf8String(
+      content,
+      'project scratchpad',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.setProjectScratchpadInState(
+      state,
+      stored,
+      content,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async appendProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+    content: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    validateUtf8String(
+      content,
+      'project scratchpad append',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.appendProjectScratchpadInState(
+      state,
+      stored,
+      content,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
+    return this.clearProjectScratchpadInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  private requireProjectManagementTools(): INormalizedProjectManagementTools {
+    const projectManagement = this.core.builtInTools.projectManagement;
+    if (!projectManagement) {
+      throw new FlexHarnessValidationError('Project management is not configured for this FlexHarness.');
+    }
+    return projectManagement;
+  }
+
+  public projectManagementKey(storageKey: string, sessionId: string): string {
+    return JSON.stringify([storageKey, sessionId]);
+  }
+
+  private queueProjectManagementOperation<TResult>(
+    storageKey: string,
+    sessionId: string,
+    operation: () => Promise<TResult>,
+  ): Promise<TResult> {
+    return queueOperation(this.projectManagementQueues, this.projectManagementKey(storageKey, sessionId), operation);
+  }
+
+  public async awaitProjectManagementOperations(
+    storageKey: string,
+    sessionIds: Iterable<string>,
+  ): Promise<void> {
+    const barriers = [...new Set(sessionIds)]
+      .map((sessionId) => this.projectManagementQueues.get(
+        this.projectManagementKey(storageKey, sessionId),
+      ))
+      .filter((barrier): barrier is Promise<void> => barrier !== undefined);
+    await Promise.all(barriers);
+  }
+
+  private async resolveProjectManagementSession(
+    scopeId: string,
+    sessionId: string,
+    access: 'read' | 'write',
+  ): Promise<{ state: IStorageState; stored: IStoredSessionState }> {
+    this.requireProjectManagementTools();
+    const { state } = await this.core.resolveState(scopeId);
+    await state.scopeQueue;
+    this.core.assertOpen();
+    this.core.assertStateAcceptingWork(state);
+    const stored = this.core.requireSession(state, sessionId);
+    if (access === 'write') this.core.assertSessionWritable(stored);
+    return { state, stored };
+  }
+
+  private assertProjectManagementSession(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): void {
+    this.core.assertOpen();
+    this.core.assertStateAcceptingWork(state);
+    if (
+      state.sessions.get(stored.session.sessionId) !== stored
+      || state.tombstones.has(stored.session.sessionId)
+    ) {
+      throw new FlexHarnessNotFoundError('Session', stored.session.sessionId);
+    }
+  }
+
+  private async loadProjectManagementState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): Promise<IFlexProjectManagementSnapshot> {
+    const store = this.core.stores.projectManagement;
+    const generation = requireSessionGeneration(stored.session);
+    const sessionContext = this.createProjectManagementSessionContext(state, stored.session);
+    const record = await store.load(
+      state.storageKey,
+      stored.session.sessionId,
+      sessionContext,
+    );
+    if (record === undefined) {
+      return createEmptyFlexProjectManagementSnapshot(
+        generation.sessionGenerationId,
+        generation.sessionGenerationSequence,
+      );
+    }
+    assertFlexProjectManagementRecord(record);
+    if (record.sessionGenerationId === generation.sessionGenerationId) {
+      if (record.sessionGenerationSequence !== generation.sessionGenerationSequence) {
+        throw new FlexHarnessStoreConflictError(
+          this.projectManagementKey(state.storageKey, stored.session.sessionId),
+          0,
+          record.revision,
+        );
+      }
+      if (!('deletedAt' in record)) return cloneSerializable(record);
+      throw new FlexHarnessNotFoundError('Project management state', stored.session.sessionId);
+    }
+    if (
+      'deletedAt' in record
+      && record.sessionGenerationSequence < generation.sessionGenerationSequence
+    ) {
+      return createEmptyFlexProjectManagementSnapshot(
+        generation.sessionGenerationId,
+        generation.sessionGenerationSequence,
+      );
+    }
+    throw new FlexHarnessStoreConflictError(
+      this.projectManagementKey(state.storageKey, stored.session.sessionId),
+      0,
+      record.revision,
+    );
+  }
+
+  private readProjectManagementState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): Promise<IFlexProjectManagementSnapshot> {
+    return this.queueProjectManagementOperation(
+      state.storageKey,
+      stored.session.sessionId,
+      async () => {
+        this.assertProjectManagementSession(state, stored);
+        const snapshot = await this.loadProjectManagementState(state, stored);
+        this.assertProjectManagementSession(state, stored);
+        return publicSnapshot(snapshot);
+      },
+    );
+  }
+
+  private mutateProjectManagementState<TResult>(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+    mutation: (
+      snapshot: IFlexProjectManagementSnapshot,
+    ) => { changed: boolean; value: TResult },
+  ): Promise<{ snapshot: IFlexProjectManagementSnapshot; value: TResult }> {
+    return this.queueProjectManagementOperation(
+      state.storageKey,
+      stored.session.sessionId,
+      async () => {
+        this.assertProjectManagementSession(state, stored);
+        const snapshot = await this.loadProjectManagementState(state, stored);
+        this.assertProjectManagementSession(state, stored);
+        const expectedRevision = snapshot.revision;
+        const result = mutation(snapshot);
+        if (result.changed) {
+          snapshot.revision = expectedRevision + 1;
+          assertFlexProjectManagementSnapshot(snapshot);
+          this.assertProjectManagementSession(state, stored);
+          await this.core.stores.projectManagement.save(
+            state.storageKey,
+            stored.session.sessionId,
+            cloneSerializable(snapshot),
+            expectedRevision,
+            Object.freeze(cloneSerializable(writeContext)),
+          );
+        }
+        return {
+          snapshot: publicSnapshot(snapshot),
+          value: result.value === undefined ? result.value : publicSnapshot(result.value),
+        };
+      },
+    );
+  }
+
+  private projectStateResult(snapshot: IFlexProjectManagementSnapshot): IFlexProjectStateResult {
+    return publicSnapshot({ revision: snapshot.revision, state: snapshot });
+  }
+
+  private createProjectManagementSessionContext(
+    state: IStorageState,
+    session: Readonly<IFlexSession | IFlexSessionTombstone>,
+  ): Readonly<IFlexProjectManagementSessionContext> {
+    const source = 'deletedAt' in session
+      ? session.subagent
+      : this.core.subagentTasks.createSubagentProvenance(state, session);
+    const subagent = source === undefined
+      ? undefined
+      : Object.freeze({ ...cloneSerializable(source) });
+    return Object.freeze({
+      ...requireSessionGeneration(session),
+      ...(subagent === undefined ? {} : { subagent }),
+    });
+  }
+
+  private projectTaskResult(
+    snapshot: IFlexProjectManagementSnapshot,
+    task: IFlexProjectTask,
+  ): IFlexProjectTaskResult {
+    return publicSnapshot({ revision: snapshot.revision, task, state: snapshot });
+  }
+
+  private projectTasksResult(
+    snapshot: IFlexProjectManagementSnapshot,
+    tasks: IFlexProjectTask[],
+  ): IFlexProjectTasksResult {
+    return publicSnapshot({ revision: snapshot.revision, tasks, state: snapshot });
+  }
+
+  private projectGoalResult(snapshot: IFlexProjectManagementSnapshot): IFlexProjectGoalResult {
+    return publicSnapshot({
+      revision: snapshot.revision,
+      goal: snapshot.goal ?? null,
+      state: snapshot,
+    });
+  }
+
+  private projectScratchpadResult(
+    snapshot: IFlexProjectManagementSnapshot,
+  ): IFlexProjectScratchpadResult {
+    return publicSnapshot({
+      revision: snapshot.revision,
+      scratchpad: snapshot.scratchpad,
+      state: snapshot,
+    });
+  }
+
+  private async createProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    input: IFlexCreateProjectTaskInput,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const status = input.status ?? 'pending';
+    const priority = input.priority ?? 'medium';
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const existing = snapshot.tasks.find((task) => task.id === input.id);
+        if (existing) {
+          if (
+            existing.content === input.content
+            && existing.status === status
+            && existing.priority === priority
+          ) return { changed: false, value: existing };
+          throw new FlexHarnessValidationError(
+            `Project task "${input.id}" already exists with different creation data.`,
+          );
+        }
+        if (snapshot.tasks.length >= FLEX_PROJECT_MANAGEMENT_LIMITS.maxTasks) {
+          throw new FlexHarnessValidationError('Project task count has reached its limit.');
+        }
+        const timestamp = new Date().toISOString();
+        const task: IFlexProjectTask = {
+          id: input.id,
+          content: input.content,
+          status,
+          priority,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        };
+        snapshot.tasks.push(task);
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async updateProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    input: IFlexUpdateProjectTaskInput,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const task = snapshot.tasks.find((entry) => entry.id === input.id);
+        if (!task) throw new FlexHarnessNotFoundError('Project task', input.id);
+        const changed = (input.content !== undefined && input.content !== task.content)
+          || (input.status !== undefined && input.status !== task.status)
+          || (input.priority !== undefined && input.priority !== task.priority);
+        if (!changed) return { changed: false, value: task };
+        if (input.content !== undefined) task.content = input.content;
+        if (input.status !== undefined) task.status = input.status;
+        if (input.priority !== undefined) task.priority = input.priority;
+        task.updatedAt = new Date().toISOString();
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async deleteProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    taskId: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const index = snapshot.tasks.findIndex((task) => task.id === taskId);
+        if (index < 0) throw new FlexHarnessNotFoundError('Project task', taskId);
+        const [task] = snapshot.tasks.splice(index, 1);
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async clearProjectTasksInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTasksResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const tasks = snapshot.tasks;
+        if (tasks.length === 0) return { changed: false, value: [] as IFlexProjectTask[] };
+        snapshot.tasks = [];
+        return { changed: true, value: tasks };
+      },
+    );
+    return this.projectTasksResult(result.snapshot, result.value);
+  }
+
+  private async setProjectGoalInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    goal: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectGoalResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.goal === goal) return { changed: false, value: undefined };
+        snapshot.goal = goal;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectGoalResult(result.snapshot);
+  }
+
+  private async clearProjectGoalInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectGoalResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.goal === undefined) return { changed: false, value: undefined };
+        delete snapshot.goal;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectGoalResult(result.snapshot);
+  }
+
+  private async setProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    content: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.scratchpad === content) return { changed: false, value: undefined };
+        snapshot.scratchpad = content;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
+  private async appendProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    content: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (content.length === 0) return { changed: false, value: undefined };
+        const appended = `${snapshot.scratchpad}${content}`;
+        validateUtf8String(
+          appended,
+          'project scratchpad',
+          FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+        );
+        snapshot.scratchpad = appended;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
+  private async clearProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.scratchpad.length === 0) return { changed: false, value: undefined };
+        snapshot.scratchpad = '';
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
+  public createProjectTaskTool(run: IActiveRun): unknown {
+    const status = plugins.z.enum(['pending', 'in_progress', 'completed', 'cancelled']);
+    const priority = plugins.z.enum(['high', 'medium', 'low']);
+    const id = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes);
+    const content = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes);
+    return plugins.tool({
+      description: 'List, create, update, delete, or clear session-local project tasks.',
+      strict: false,
+      inputSchema: plugins.z.object({
+        action: plugins.z.enum(['list', 'create', 'update', 'delete', 'clear']),
+        id: id.optional(),
+        content: content.optional(),
+        status: status.optional(),
+        priority: priority.optional(),
+      }).strict().superRefine((input, context) => {
+        const rejectFields = (...fields: Array<keyof typeof input>): void => {
+          for (const field of fields) {
+            if (input[field] === undefined) continue;
+            context.addIssue({
+              code: 'custom',
+              path: [field],
+              message: `Task action "${input.action}" does not accept ${field}.`,
+            });
+          }
+        };
+        if (input.action === 'list' || input.action === 'clear') {
+          rejectFields('id', 'content', 'status', 'priority');
+        } else if (input.action === 'create') {
+          if (input.content === undefined) {
+            context.addIssue({
+              code: 'custom',
+              path: ['content'],
+              message: 'Task creation requires content.',
+            });
+          }
+        } else if (input.action === 'update') {
+          if (input.id === undefined) {
+            context.addIssue({
+              code: 'custom',
+              path: ['id'],
+              message: 'Task update requires an id.',
+            });
+          }
+          if (
+            input.content === undefined
+            && input.status === undefined
+            && input.priority === undefined
+          ) {
+            context.addIssue({
+              code: 'custom',
+              message: 'Task update requires content, status, or priority.',
+            });
+          }
+        } else {
+          if (input.id === undefined) {
+            context.addIssue({
+              code: 'custom',
+              path: ['id'],
+              message: 'Task deletion requires an id.',
+            });
+          }
+          rejectFields('content', 'status', 'priority');
+        }
+      }),
+      execute: (
+        input,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectTaskTool(
+        run,
+        input as TProjectTaskToolInput,
+        options?.toolCallId,
+      ),
+    });
+  }
+
+  public createProjectGoalTool(run: IActiveRun): unknown {
+    return plugins.tool({
+      description: 'Get, set, or clear the session-local project goal.',
+      strict: false,
+      inputSchema: plugins.z.object({
+        action: plugins.z.enum(['get', 'set', 'clear']),
+        goal: plugins.z.string()
+          .min(1)
+          .max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes)
+          .optional(),
+      }).strict().superRefine((input, context) => {
+        if (input.action === 'set' && input.goal === undefined) {
+          context.addIssue({
+            code: 'custom',
+            path: ['goal'],
+            message: 'Goal set requires a goal.',
+          });
+        } else if (input.action !== 'set' && input.goal !== undefined) {
+          context.addIssue({
+            code: 'custom',
+            path: ['goal'],
+            message: `Goal action "${input.action}" does not accept goal.`,
+          });
+        }
+      }),
+      execute: (
+        input,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectGoalTool(
+        run,
+        input as TProjectGoalToolInput,
+        options?.toolCallId,
+      ),
+    });
+  }
+
+  public createProjectScratchpadTool(run: IActiveRun): unknown {
+    const content = plugins.z.string().max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes);
+    return plugins.tool({
+      description: 'Get, set, append to, or clear the session-local project scratchpad.',
+      strict: false,
+      inputSchema: plugins.z.object({
+        action: plugins.z.enum(['get', 'set', 'append', 'clear']),
+        content: content.optional(),
+      }).strict().superRefine((input, context) => {
+        if (
+          (input.action === 'set' || input.action === 'append')
+          && input.content === undefined
+        ) {
+          context.addIssue({
+            code: 'custom',
+            path: ['content'],
+            message: `Scratchpad ${input.action} requires content.`,
+          });
+        } else if (
+          (input.action === 'get' || input.action === 'clear')
+          && input.content !== undefined
+        ) {
+          context.addIssue({
+            code: 'custom',
+            path: ['content'],
+            message: `Scratchpad action "${input.action}" does not accept content.`,
+          });
+        }
+      }),
+      execute: (
+        input,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectScratchpadTool(
+        run,
+        input as TProjectScratchpadToolInput,
+        options?.toolCallId,
+      ),
+    });
+  }
+
+  private projectManagementAgentWriteContext(
+    run: IActiveRun,
+    toolCallId: string | undefined,
+  ): IFlexProjectManagementWriteContext {
+    return Object.freeze({
+      actor: 'agent' as const,
+      runId: run.runId,
+      ...(run.stored.session.agent === undefined ? {} : { agent: run.stored.session.agent }),
+      ...(toolCallId === undefined ? {} : { toolCallId }),
+    });
+  }
+
+  private async executeProjectTaskTool(
+    run: IActiveRun,
+    input: TProjectTaskToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectStateResult | IFlexProjectTaskResult | IFlexProjectTasksResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'list') {
+      const snapshot = await this.readProjectManagementState(run.state, run.stored);
+      return this.projectTasksResult(snapshot, snapshot.tasks);
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'create') {
+      const id = input.id ?? (() => {
+        validateUtf8String(
+          toolCallId,
+          'task toolCallId',
+          maxTransferIdentifierBytes,
+          true,
+        );
+        return this.createProjectTaskId(
+          run.state.storageKey,
+          run.sessionId,
+          run.runId,
+          toolCallId,
+        );
+      })();
+      const createInput: IFlexCreateProjectTaskInput = {
+        id,
+        content: input.content,
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+      };
+      validateCreateProjectTaskInput(createInput);
+      return this.createProjectTaskInState(run.state, run.stored, createInput, writeContext);
+    }
+    if (input.action === 'update') {
+      const updateInput: IFlexUpdateProjectTaskInput = {
+        id: input.id,
+        ...(input.content === undefined ? {} : { content: input.content }),
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+      };
+      validateUpdateProjectTaskInput(updateInput);
+      return this.updateProjectTaskInState(run.state, run.stored, updateInput, writeContext);
+    }
+    if (input.action === 'delete') {
+      validateProjectTaskId(input.id);
+      return this.deleteProjectTaskInState(run.state, run.stored, input.id, writeContext);
+    }
+    return this.clearProjectTasksInState(run.state, run.stored, writeContext);
+  }
+
+  private async executeProjectGoalTool(
+    run: IActiveRun,
+    input: TProjectGoalToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectGoalResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'get') {
+      return this.projectGoalResult(await this.readProjectManagementState(run.state, run.stored));
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'set') {
+      validateUtf8String(
+        input.goal,
+        'project goal',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+        true,
+      );
+      return this.setProjectGoalInState(run.state, run.stored, input.goal, writeContext);
+    }
+    return this.clearProjectGoalInState(run.state, run.stored, writeContext);
+  }
+
+  private async executeProjectScratchpadTool(
+    run: IActiveRun,
+    input: TProjectScratchpadToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectScratchpadResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'get') {
+      return this.projectScratchpadResult(
+        await this.readProjectManagementState(run.state, run.stored),
+      );
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'set') {
+      validateUtf8String(
+        input.content,
+        'project scratchpad',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+      );
+      return this.setProjectScratchpadInState(run.state, run.stored, input.content, writeContext);
+    }
+    if (input.action === 'append') {
+      validateUtf8String(
+        input.content,
+        'project scratchpad append',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+      );
+      return this.appendProjectScratchpadInState(
+        run.state,
+        run.stored,
+        input.content,
+        writeContext,
+      );
+    }
+    return this.clearProjectScratchpadInState(run.state, run.stored, writeContext);
+  }
+
+  private createProjectTaskId(
+    storageKey: string,
+    sessionId: string,
+    runId: string,
+    toolCallId: string,
+  ): string {
+    return `task_${sha256Hex(JSON.stringify([
+      'flexharness-project-task-v1',
+      storageKey,
+      sessionId,
+      runId,
+      toolCallId,
+    ]))}`;
+  }
+
+  public async tombstoneProjectManagementSession(
+    state: IStorageState,
+    sessionTombstone: IFlexSessionTombstone,
+  ): Promise<void> {
+    const storageKey = state.storageKey;
+    const store = this.core.stores.projectManagement;
+    const sessionId = sessionTombstone.sessionId;
+    const generation = requireSessionGeneration(sessionTombstone);
+    const sessionContext = this.createProjectManagementSessionContext(state, sessionTombstone);
+    let lastConflict: FlexHarnessStoreConflictError | undefined;
+    for (let attempt = 0; attempt <= maxProjectManagementTombstoneConflicts; attempt++) {
+      const current = await store.load(
+        storageKey,
+        sessionId,
+        sessionContext,
+      );
+      if (current !== undefined) {
+        assertFlexProjectManagementRecord(current);
+        if (current.sessionGenerationId === generation.sessionGenerationId) {
+          if (current.sessionGenerationSequence !== generation.sessionGenerationSequence) {
+            throw new FlexHarnessStoreConflictError(
+              this.projectManagementKey(storageKey, sessionId),
+              0,
+              current.revision,
+            );
+          }
+          if ('deletedAt' in current) return;
+        } else if (
+          !('deletedAt' in current)
+          || current.sessionGenerationSequence >= generation.sessionGenerationSequence
+        ) {
+          throw new FlexHarnessStoreConflictError(
+            this.projectManagementKey(storageKey, sessionId),
+            0,
+            current.revision,
+          );
+        }
+      }
+      if (attempt === maxProjectManagementTombstoneConflicts) break;
+      const expectedRevision = current === undefined
+        || current.sessionGenerationId !== generation.sessionGenerationId
+        ? 0
+        : current.revision;
+      const tombstone: IFlexProjectManagementTombstone = {
+        schemaVersion: 1,
+        revision: expectedRevision + 1,
+        ...generation,
+        deletedAt: sessionTombstone.deletedAt,
+      };
+      try {
+        await store.tombstoneSession(
+          storageKey,
+          sessionId,
+          tombstone,
+          expectedRevision,
+          sessionContext,
+        );
+      } catch (error) {
+        if (!(error instanceof FlexHarnessStoreConflictError)) throw error;
+        lastConflict = error;
+      }
+    }
+    throw lastConflict ?? new FlexHarnessValidationError(
+      `Project management tombstone for session "${sessionId}" could not be durably confirmed.`,
+    );
+  }
+}