taskchef 5.11.2 → 6.0.0

package/src/delegation.js

@@ -1,30 +1,22 @@
 import { randomUUID } from "node:crypto";
 
-// Bounded discovery parameters used when Codex returns only a provisional
-// client ID. Candidate content still needs exact-marker verification.
-export const THREAD_RESOLUTION_CHECKPOINTS_MS = Object.freeze([10_000, 30_000]);
-export const THREAD_RESOLUTION_TIMEOUT_MS = 30_000;
-export const THREAD_RESOLUTION_RECENT_LIMIT = 50;
-export const THREAD_RESOLUTION_CLOCK_SKEW_MS = 5_000;
 export const EXECUTOR_OWNERSHIP_PARAGRAPH = "This task owns the delegated assignment. Execute it in this task; do not re-dispatch it merely because it concerns TaskChef or a configured project. Explicit requests to delegate separate work remain valid.";
-export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+export const EXECUTOR_LINK_PARAGRAPH = "Before any other work, read this executor's own durable Codex thread ID from the current task's CODEX_THREAD_ID environment value and call the TaskChef link_task MCP tool with that thread ID and the marked TaskChef task ID. Never use CODEX_SESSION_ID or the parent or delegator thread ID. If linking fails, CODEX_THREAD_ID is unavailable, or the tool is unavailable, report the failure visibly and retry on a later turn; do not guess an identity or continue substantive work while the task is link-pending.";
+export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with the marked task ID, this executor's self-linked thread ID, the current turn ID from an exact native read of that same thread, completed, needs_input, or failed, and a concise summary. Never reuse a prior turn ID after a follow-up. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
 
 const UUID_SOURCE = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
 const UUID_PATTERN = new RegExp(`^${UUID_SOURCE}$`);
+const CODEX_UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const TASKCHEF_MARKER_PATTERN = new RegExp(`^<!-- taskchef_id=(${UUID_SOURCE}) -->$`);
 const LEGACY_TASKCHEF_MARKER_PATTERN = new RegExp(`^# taskchef_id=(${UUID_SOURCE})$`);
 
 function requireObject(value, name) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${name} must be an object`);
-  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
   return value;
 }
 
 function requireString(value, name) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${name} must be a non-empty string`);
-  }
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${name} must be a non-empty string`);
   return value;
 }
 
@@ -44,11 +36,6 @@ function parseToolResult(value, name) {
   }
 }
 
-function timestampMilliseconds(value) {
-  if (typeof value !== "number" || !Number.isFinite(value)) return null;
-  return value < 1_000_000_000_000 ? value * 1_000 : value;
-}
-
 function toolIdentifier(value) {
   if (typeof value !== "string") return null;
   const normalized = value.trim();
@@ -64,10 +51,7 @@ function attachCreationRecovery(error, taskId, resultReporting) {
     });
     return creationError;
   } catch {
-    const wrapped = new Error(
-      `Executor creation failed for recorded TaskChef task ${taskId}.`,
-      { cause: creationError },
-    );
+    const wrapped = new Error(`Executor creation failed for recorded TaskChef task ${taskId}.`, { cause: creationError });
     wrapped.taskChefTaskId = taskId;
     wrapped.taskChefResultReporting = resultReporting;
     return wrapped;
@@ -82,12 +66,17 @@ export function isProvisionalThreadId(value) {
 export function normalizeDurableThreadId(value, name = "threadId") {
   const id = toolIdentifier(value);
   if (id === null) throw new Error(`${name} must be a non-empty string`);
-  if (isProvisionalThreadId(id)) {
-    throw new Error(`${name} must be a durable thread ID, not a provisional local ID`);
-  }
+  if (isProvisionalThreadId(id)) throw new Error(`${name} must be a durable thread ID, not a provisional local ID`);
   return id;
 }
 
+export function normalizeCodexThreadId(value, name = "threadId") {
+  const id = normalizeDurableThreadId(value, name).toLowerCase();
+  if (!CODEX_UUID_V7_PATTERN.test(id)) {
+    throw new Error(`${name} must be a canonical Codex UUIDv7`);
+  }
+  return id;
+}
 
 export function taskChefMarker(taskId) {
   return `<!-- taskchef_id=${requireUuid(taskId)} -->`;
@@ -107,149 +96,35 @@ export function parseTaskChefMarker(instruction, { allowLegacyHeading = false }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
   requireString(instruction, "instruction");
-  if (parseTaskChefMarker(instruction) !== null) {
-    throw new Error("instruction already contains a TaskChef marker");
-  }
+  if (parseTaskChefMarker(instruction) !== null) throw new Error("instruction already contains a TaskChef marker");
   const id = requireUuid(taskId);
   return {
     id,
-    instruction: `${taskChefMarker(id)}\n\n${EXECUTOR_OWNERSHIP_PARAGRAPH}\n\n${EXECUTOR_RESULT_PARAGRAPH}\n\n${instruction}`,
+    instruction: `${taskChefMarker(id)}\n\n${EXECUTOR_OWNERSHIP_PARAGRAPH}\n\n${EXECUTOR_LINK_PARAGRAPH}\n\n${EXECUTOR_RESULT_PARAGRAPH}\n\n${instruction}`,
   };
 }
 
-export function listThreadEntries(result) {
-  const parsed = parseToolResult(result, "list_threads result");
-  const entries = [...(parsed.pinnedThreads ?? []), ...(parsed.threads ?? [])];
-  const unique = new Map();
-  for (const entry of entries) {
-    const id = toolIdentifier(entry?.id);
-    if (id !== null && !unique.has(id)) unique.set(id, { ...entry, id });
-  }
-  return [...unique.values()];
-}
-
-export function structuredDelegatedInputs(result) {
-  const parsed = parseToolResult(result, "read_thread result");
-  const inputs = [];
-  for (const turn of parsed.turns ?? []) {
-    for (const item of turn?.items ?? []) {
-      if (item?.type !== "userMessage") continue;
-      for (const part of item.content ?? []) {
-        if (typeof part?.codexDelegation?.input === "string") {
-          inputs.push(part.codexDelegation.input);
-        }
-      }
-    }
-  }
-  return inputs;
-}
-
-export function hasExactTaskChefMarker(result, taskId) {
-  const id = requireUuid(taskId);
-  return structuredDelegatedInputs(result).some(
-    (input) => parseTaskChefMarker(input) === id,
-  );
-}
-
-export function filterThreadCandidates(result, {
-  baselineThreadIds = new Set(),
-  excludedThreadIds = new Set(),
-  hostId = null,
-  projectId = null,
-  title = null,
-  createdAfter = null,
-  environmentType = null,
-} = {}) {
-  const minimumCreatedAt = createdAfter === null
-    ? null
-    : timestampMilliseconds(createdAfter) - THREAD_RESOLUTION_CLOCK_SKEW_MS;
-  const candidates = listThreadEntries(result).filter((thread) => {
-    if (
-      baselineThreadIds.has(thread.id)
-      || excludedThreadIds.has(thread.id)
-      || isProvisionalThreadId(thread.id)
-      || thread.kind !== "codex"
-    ) return false;
-    if (hostId !== null && thread.hostId !== undefined && thread.hostId !== hostId) return false;
-    if (projectId !== null && thread.projectId !== undefined && thread.projectId !== projectId) {
-      return false;
-    }
-    const candidateEnvironmentType = thread.environment?.type
-      ?? thread.environmentType
-      ?? thread.backing?.environment?.type;
-    if (
-      environmentType !== null
-      && candidateEnvironmentType !== undefined
-      && candidateEnvironmentType !== environmentType
-    ) return false;
-    const candidateTime = timestampMilliseconds(thread.createdAt ?? thread.updatedAt);
-    if (minimumCreatedAt !== null && candidateTime !== null && candidateTime < minimumCreatedAt) {
-      return false;
-    }
-    return true;
-  });
-  if (title === null) return candidates;
-  return candidates.sort((left, right) =>
-    Number(right.title === title) - Number(left.title === title));
-}
-
 export async function createAndRecordDelegation(input) {
-  const {
-    project,
-    title,
-    instruction,
-    target,
-    createThread,
-    recordTask,
-    resolveRecordedTask = null,
-    reportRecordedResult = null,
-    taskId = randomUUID(),
-  } = input ?? {};
+  const { project, title, instruction, target, createThread, recordTask, reportRecordedResult = null, taskId = randomUUID() } = input ?? {};
   requireString(project, "project");
   requireString(title, "title");
   requireObject(target, "target");
-  for (const [value, name] of [
-    [createThread, "createThread"],
-    [recordTask, "recordTask"],
-  ]) {
+  for (const [value, name] of [[createThread, "createThread"], [recordTask, "recordTask"]]) {
     if (typeof value !== "function") throw new Error(`${name} must be a function`);
   }
-  for (const [value, name] of [
-    [resolveRecordedTask, "resolveRecordedTask"],
-    [reportRecordedResult, "reportRecordedResult"],
-  ]) {
-    if (value !== null && typeof value !== "function") {
-      throw new Error(`${name} must be a function or null`);
-    }
-  }
+  if (reportRecordedResult !== null && typeof reportRecordedResult !== "function") throw new Error("reportRecordedResult must be a function or null");
 
   const prepared = prepareDelegation(instruction, { taskId });
-  await recordTask({
-    id: prepared.id,
-    project,
-    title,
-    instruction: prepared.instruction,
-    threadId: null,
-  });
+  await recordTask({ id: prepared.id, project, title, instruction: prepared.instruction, threadId: null });
 
   let createResult;
   try {
-    createResult = parseToolResult(await createThread({
-      prompt: prepared.instruction,
-      title,
-      target,
-    }), "create_thread result");
+    createResult = parseToolResult(await createThread({ prompt: prepared.instruction, title, target }), "create_thread result");
   } catch (error) {
     let resultReporting = "unavailable";
     if (reportRecordedResult !== null) {
       try {
-        await reportRecordedResult({
-          taskId: prepared.id,
-          threadId: null,
-          turnId: null,
-          status: "failed",
-          summary: "Executor creation failed before the executor started.",
-        });
+        await reportRecordedResult({ taskId: prepared.id, threadId: null, turnId: null, status: "failed", summary: "Executor creation failed before the executor started." });
         resultReporting = "recorded";
       } catch {
         resultReporting = "failed";
@@ -261,58 +136,6 @@ export async function createAndRecordDelegation(input) {
   const returnedThreadId = toolIdentifier(createResult.threadId);
   const clientThreadId = toolIdentifier(createResult.clientThreadId);
   const pendingWorktreeId = toolIdentifier(createResult.pendingWorktreeId);
-  const provisional = clientThreadId
-    ?? pendingWorktreeId
-    ?? (isProvisionalThreadId(returnedThreadId) ? returnedThreadId : null);
-  const durableThreadId = returnedThreadId !== null
-    && !isProvisionalThreadId(returnedThreadId)
-    && returnedThreadId !== clientThreadId
-    && returnedThreadId !== pendingWorktreeId
-      ? returnedThreadId
-      : null;
-
-  if (durableThreadId !== null) {
-    if (resolveRecordedTask !== null) {
-      try {
-        await resolveRecordedTask({ id: prepared.id, threadId: durableThreadId });
-        return {
-          status: "recorded",
-          resolution: "immediate",
-          ...prepared,
-          threadId: durableThreadId,
-          provisional,
-          hostId: createResult.hostId ?? null,
-        };
-      } catch (error) {
-        return {
-          status: "recorded-unresolved",
-          reason: "task-resolution-failed",
-          resolutionError: error instanceof Error ? error.message : String(error),
-          ...prepared,
-          threadId: null,
-          createdThreadId: durableThreadId,
-          provisional,
-          hostId: createResult.hostId ?? null,
-        };
-      }
-    }
-    return {
-      status: "recorded-unresolved",
-      reason: "task-resolution-unavailable",
-      ...prepared,
-      threadId: null,
-      createdThreadId: durableThreadId,
-      provisional,
-      hostId: createResult.hostId ?? null,
-    };
-  }
-
-  return {
-    status: "recorded-unresolved",
-    reason: "awaiting-bounded-marker-resolution",
-    ...prepared,
-    threadId: null,
-    provisional,
-    hostId: createResult.hostId ?? null,
-  };
+  const provisional = clientThreadId ?? pendingWorktreeId ?? (isProvisionalThreadId(returnedThreadId) ? returnedThreadId : null);
+  return { status: "recorded-link-pending", resolution: "executor-self-link", ...prepared, threadId: null, provisional, hostId: createResult.hostId ?? null };
 }

package/src/mcp.js

@@ -2,9 +2,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import {
   prepareDispatch,
+  linkTask,
   recordTask,
   reportTaskResult,
-  resolveTask,
 } from "./workspace.js";
 import { parseTaskChefMarker } from "./delegation.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
@@ -54,13 +54,13 @@ export function createTaskChefMcpServer({
   prepare = prepareDispatch,
   record = recordTask,
   reportResult = reportTaskResult,
-  resolve = resolveTask,
+  link = linkTask,
 } = {}) {
   const server = new McpServer(
     { name: "taskchef", version: "1.0.0" },
     {
       instructions:
-        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively. Use resolve_task for a durable root thread ID. Executors must call report_result before ending with completed, needs_input, or failed.",
+        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively and return immediately. The executor must call link_task before other work and report_result before ending.",
     },
   );
 
@@ -89,13 +89,13 @@ export function createTaskChefMcpServer({
     {
       title: "Record TaskChef task",
       description:
-        "Atomically append one prepared TaskChef task before creating its Codex executor. Pass the exact marked instruction and use null for threadId until a durable root ID is known.",
+        "Atomically append one prepared TaskChef task before creating its Codex executor. Pass the exact marked instruction and null threadId; only the executor may self-link it.",
       inputSchema: {
         id: z.string().min(1),
         project: z.string().min(1),
         title: z.string().min(1),
         instruction: z.string().min(1),
-        threadId: z.string().min(1).nullable(),
+        threadId: z.null(),
       },
       outputSchema: { task: taskSchema },
       annotations: {
@@ -114,11 +114,11 @@ export function createTaskChefMcpServer({
   );
 
   server.registerTool(
-    "resolve_task",
+    "link_task",
     {
-      title: "Resolve TaskChef task",
+      title: "Link TaskChef executor",
       description:
-        "Atomically fill one recorded TaskChef task's nullable thread ID after exactly one structured marker match. The one-way transition cannot overwrite another durable ID.",
+        "Register this executor's asserted durable Codex thread ID. The atomic one-way transition is idempotent and rejects conflicts or thread reuse.",
       inputSchema: {
         taskId: z.string().min(1),
         threadId: z.string().min(1),
@@ -131,8 +131,8 @@ export function createTaskChefMcpServer({
       },
     },
     async ({ taskId, threadId }) => {
-      const task = await resolve(workspace, taskId, threadId);
-      return toolResult("task", task, `Resolved TaskChef task ${task.id}.`);
+      const task = await link(workspace, taskId, threadId);
+      return toolResult("task", task, `Linked TaskChef task ${task.id}.`);
     },
   );