/**
 * Shared agent tool factory functions.
 *
 * Extracted from TaskExecutor so they can be reused by other subsystems
 * (e.g., HeartbeatMonitor execution) without pulling in the full executor.
 *
 * The parameter schemas are canonical here — executor.ts imports and reuses them.
 */

import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { createHash } from "node:crypto";
import { join, relative, resolve } from "node:path";
import type { AgentState, AgentCapability, AgentUpdateInput, TaskDocument, TaskDocumentCreateInput, TaskStore, RunMutationContext, MessageStore, Message, SourceType, Settings, ResearchRun, ResearchRunStatus, TaskCreateInput, ReflectionStore, ApprovalRequestStore, ProjectSettings, ChatStore } from "@fusion/core";
import { listTraits, isBuiltinWorkflowId, AgentStore, validateColumnAgentBindings, ColumnAgentBindingError, stripApprovalBypassFlags } from "@fusion/core";
import { promoteHeldTask } from "./hold-release.js";
import { DASHBOARD_USER_ID, canAgentTakeImplementationTaskForExplicitRouting, dailyMemoryPath, ensureOpenClawMemoryFiles, extractAgentProvisioningRequest, formatRoleMismatchReason, getMemoryBackendCapabilities, getProjectMemory, isEphemeralAgent, memoryLongTermPath, normalizeMessageParticipant, reconcileDeterministicDuplicate, resolveAgentProvisioningPolicy, resolveMemoryBackend, resolveResearchSettings, resolveTaskGithubTracking, resolveTitleSummarizerSettingsModel, runDeterministicDuplicateGuard, scheduleQmdProjectMemoryRefresh, searchProjectMemory, shouldSkipBackgroundQmdRefresh, summarizeTitle } from "@fusion/core";
import { ResearchOrchestrator } from "./research-orchestrator.js";
import { ResearchProviderRegistry } from "./research/provider-registry.js";
import { ResearchStepRunner } from "./research-step-runner.js";
import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
import { Type, type Static } from "@earendil-works/pi-ai";
import type { AgentReflectionService } from "./agent-reflection.js";
import { createLogger } from "./logger.js";
import { fetchWebContent, WebFetchError } from "./web-fetch.js";
import type { RunAuditor } from "./run-audit.js";
import { computeApprovalDedupeKey } from "./agent-action-gate.js";
import { MessageDeliveryAutoRecoveryHandler } from "./auto-recovery-handlers/message-delivery.js";
import { recordRetry } from "./retry-burned-logger.js";

// ── Tool parameter schemas (canonical definitions) ────────────────────────

const TASK_CREATE_PRIORITY_VALUES = ["low", "normal", "high", "urgent"] as const;

export const taskCreateParams = Type.Object({
  description: Type.String({ description: "What needs to be done" }),
  dependencies: Type.Optional(
    Type.Array(Type.String(), { description: "Task IDs this new task depends on (e.g. [\"KB-001\"])" }),
  ),
  priority: Type.Optional(
    Type.Union(TASK_CREATE_PRIORITY_VALUES.map((priority) => Type.Literal(priority)), {
      description: "Task priority (low, normal, high, urgent)",
    }),
  ),
});

export const taskLogParams = Type.Object({
  message: Type.String({ description: "What happened" }),
  outcome: Type.Optional(Type.String({ description: "Result or consequence (optional)" })),
});

export const taskDocumentWriteParams = Type.Object({
  key: Type.String({
    description: "Document key (e.g., 'plan', 'notes', 'research'). Alphanumeric, hyphens, underscores, 1-64 chars.",
  }),
  content: Type.String({ description: "Document content to store" }),
  author: Type.Optional(Type.String({ description: "Who is writing (default: 'agent')" })),
});

export const taskDocumentReadParams = Type.Object({
  key: Type.Optional(
    Type.String({ description: "Document key to read. Omit to list all documents for this task." }),
  ),
});

export const workflowListParams = Type.Object({});

export const workflowGetParams = Type.Object({
  workflow_id: Type.String({
    description:
      "The workflow definition ID to fetch (e.g. 'WF-003', or a 'builtin:*' id). " +
      "Use fn_workflow_list to discover available IDs.",
  }),
});

export const workflowSelectParams = Type.Object({
  workflow_id: Type.String({
    description:
      "The workflow definition ID to select (e.g. 'WF-003', or a 'builtin:*' id). " +
      "Use fn_workflow_list to discover available IDs.",
  }),
  task_id: Type.Optional(
    Type.String({ description: "Task to assign the workflow to. Defaults to the current task." }),
  ),
});

export const taskPromoteParams = Type.Object({
  task_id: Type.Optional(
    Type.String({ description: "Held task to promote. Defaults to the current task." }),
  ),
});

export const workflowCreateParams = Type.Object({
  name: Type.String({ description: "Workflow name (required, non-empty)." }),
  description: Type.Optional(Type.String({ description: "Optional human-readable description." })),
  ir: Type.Unknown({
    description:
      "Workflow graph (intermediate representation). Validated server-side; a malformed graph is rejected.",
  }),
  layout: Type.Optional(
    Type.Record(Type.String(), Type.Unknown(), {
      description: "Optional node layout map keyed by node id.",
    }),
  ),
  confirm_policy_escalation: Type.Optional(
    Type.Boolean({
      description:
        "Set true to confirm binding a column to an agent whose permission policy is broader " +
        "(more privileged) than the project default. Required when such a binding is present; " +
        "the create is otherwise rejected naming the offending column.",
    }),
  ),
});

export const workflowUpdateParams = Type.Object({
  workflow_id: Type.String({ description: "The workflow definition ID to update (built-ins cannot be edited)." }),
  name: Type.Optional(Type.String({ description: "New name." })),
  description: Type.Optional(Type.String({ description: "New description." })),
  ir: Type.Optional(Type.Unknown({ description: "Replacement workflow graph (validated server-side)." })),
  layout: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Replacement node layout map." })),
  rehome_to: Type.Optional(
    Type.String({
      description:
        "When an IR update removes a column that still holds cards, supply the column id to re-home those occupants into. " +
        "Required to resolve an OccupiedColumns conflict; the target must exist in the new IR.",
    }),
  ),
  confirm_policy_escalation: Type.Optional(
    Type.Boolean({
      description:
        "Set true to confirm binding a column to an agent whose permission policy is broader " +
        "(more privileged) than the project default. Required when such a binding is present; " +
        "the update is otherwise rejected naming the offending column.",
    }),
  ),
});

export const workflowDeleteParams = Type.Object({
  workflow_id: Type.String({ description: "The workflow definition ID to delete (built-ins cannot be deleted)." }),
});

export const traitListParams = Type.Object({});

export const reflectOnPerformanceParams = Type.Object({
  focus_area: Type.Optional(
    Type.String({ description: "Optional focus area for reflection (e.g., 'code quality', 'speed', 'testing')" }),
  ),
});

export const readEvaluationsParams = Type.Object({});

export const updateIdentityParams = Type.Object({
  soul: Type.Optional(Type.String({ description: "Updated soul/personality text" })),
  instructionsText: Type.Optional(Type.String({ description: "Updated operating instructions" })),
  memory: Type.Optional(Type.String({ description: "Updated agent memory text" })),
});

export const listAgentsParams = Type.Object({
  role: Type.Optional(
    Type.String({ description: "Filter by agent role/capability (e.g., 'executor', 'reviewer', 'qa')" }),
  ),
  state: Type.Optional(
    Type.String({ description: "Filter by agent state (e.g., 'idle', 'active', 'running')" }),
  ),
  includeEphemeral: Type.Optional(
    Type.Boolean({ description: "Include ephemeral/runtime agents (default: false)" }),
  ),
});

export const delegateTaskParams = Type.Object({
  agent_id: Type.String({ description: "The agent ID to delegate work to" }),
  description: Type.String({ description: "What needs to be done" }),
  dependencies: Type.Optional(
    Type.Array(Type.String(), { description: "Task IDs this new task depends on (e.g. [\"KB-001\"])" }),
  ),
  override: Type.Optional(Type.Boolean({ description: "Set true to bypass executor-role assignment policy" })),
});

export const getAgentConfigParams = Type.Object({
  agent_id: Type.String({ description: "The agent ID to read configuration for" }),
});

export const updateAgentConfigParams = Type.Object({
  agent_id: Type.String({ description: "The agent ID to update" }),
  soul: Type.Optional(Type.String({ description: "Agent personality/identity text", maxLength: 10000 })),
  instructions_text: Type.Optional(Type.String({ description: "Inline custom instructions", maxLength: 50000 })),
  instructions_path: Type.Optional(Type.String({ description: "Path to instructions markdown file", maxLength: 500 })),
  heartbeat_procedure_path: Type.Optional(Type.String({ description: "Path to heartbeat procedure markdown file", maxLength: 500 })),
  heartbeat_interval_ms: Type.Optional(Type.Number({ description: "Heartbeat polling interval in ms", minimum: 1000 })),
  heartbeat_timeout_ms: Type.Optional(Type.Number({ description: "Heartbeat timeout in ms", minimum: 5000 })),
  max_concurrent_runs: Type.Optional(Type.Number({ description: "Max concurrent heartbeat runs", minimum: 1 })),
  message_response_mode: Type.Optional(Type.Union([
    Type.Literal("immediate"),
    Type.Literal("on-heartbeat"),
  ], { description: "How agent responds to messages" })),
});

export const createAgentParams = Type.Object({
  name: Type.String({ description: "Name for the new agent" }),
  role: Type.Union([
    Type.Literal("triage"),
    Type.Literal("executor"),
    Type.Literal("reviewer"),
    Type.Literal("merger"),
    Type.Literal("engineer"),
    Type.Literal("custom"),
  ], { description: "Agent role/capability" }),
  soul: Type.Optional(Type.String({ description: "Agent personality/identity text", maxLength: 10000 })),
  instructions_text: Type.Optional(Type.String({ description: "Inline custom instructions", maxLength: 50000 })),
  instructions_path: Type.Optional(Type.String({ description: "Path to instructions markdown file", maxLength: 500 })),
  reportsTo: Type.Optional(Type.String({ description: "Manager agent ID. Defaults to the calling agent." })),
  heartbeat_interval_ms: Type.Optional(Type.Number({ description: "Heartbeat polling interval in ms", minimum: 1000 })),
  heartbeat_timeout_ms: Type.Optional(Type.Number({ description: "Heartbeat timeout in ms", minimum: 5000 })),
  max_concurrent_runs: Type.Optional(Type.Number({ description: "Max concurrent heartbeat runs", minimum: 1 })),
  message_response_mode: Type.Optional(Type.Union([
    Type.Literal("immediate"),
    Type.Literal("on-heartbeat"),
  ], { description: "How agent responds to messages" })),
});

export const deleteAgentParams = Type.Object({
  agent_id: Type.String({ description: "Agent ID to delete" }),
  force: Type.Optional(Type.Boolean({ description: "Force delete even if the agent currently holds a checkout lease" })),
  reassign_to: Type.Optional(Type.String({ description: "Optional replacement agent ID for tasks currently assigned to the deleted agent" })),
});

export const sendMessageParams = Type.Object({
  to_id: Type.String({ description: "Recipient ID (agent ID or user ID, depending on message type)" }),
  content: Type.String({ description: "Message body (1-2000 characters)" }),
  type: Type.Optional(Type.Union([
    Type.Literal("agent-to-agent"),
    Type.Literal("agent-to-user"),
  ], { description: "Message type (defaults to 'agent-to-agent')" })),
  reply_to_message_id: Type.Optional(
    Type.String({ description: "Optional ID of the message you are replying to (use IDs from fn_read_messages output)" }),
  ),
});

export const readMessagesParams = Type.Object({
  unread_only: Type.Optional(Type.Boolean({ description: "Only return unread messages (default: true)" })),
  limit: Type.Optional(Type.Number({ description: "Max messages to return (default: 20)" })),
});

export const postRoomMessageParams = Type.Object({
  roomId: Type.String({ description: "Room ID to post into" }),
  content: Type.String({ description: "Room message body (1-2000 characters)" }),
  replyToMessageId: Type.Optional(Type.String({ description: "Optional ID of the room message you are replying to" })),
  mentions: Type.Optional(Type.Array(Type.String(), { description: "Optional agent IDs to mention in the room message" })),
});

export const memorySearchParams = Type.Object({
  query: Type.String({ description: "Search terms for durable project memory. Use focused keywords, not a full prompt." }),
  limit: Type.Optional(Type.Number({ description: "Maximum snippets to return (default: 5, max: 20)" })),
});

export const memoryGetParams = Type.Object({
  path: Type.String({ description: "Memory path from fn_memory_search, e.g. .fusion/memory/MEMORY.md or .fusion/memory/YYYY-MM-DD.md" }),
  startLine: Type.Optional(Type.Number({ description: "1-based start line (default: 1)" })),
  lineCount: Type.Optional(Type.Number({ description: "Number of lines to read (default: 120, max: 400)" })),
});

export const webFetchParams = Type.Object({
  url: Type.String({ description: "URL to fetch (http/https only)" }),
  prompt: Type.Optional(Type.String({ description: "Optional extraction hint for downstream summarization" })),
  timeoutMs: Type.Optional(Type.Number({ description: "Request timeout in milliseconds" })),
  maxBytes: Type.Optional(Type.Number({ description: "Maximum content bytes to return" })),
});

export const researchRunParams = Type.Object({
  query: Type.String({ description: "Research question or topic to investigate" }),
  wait_for_completion: Type.Optional(Type.Boolean({ description: "Wait for completion in this call (default: false)" })),
  max_wait_ms: Type.Optional(Type.Number({ description: "Max wait time when wait_for_completion=true (default: 90000, capped by settings)" })),
});

export const researchListParams = Type.Object({
  status: Type.Optional(Type.Union([
    Type.Literal("pending"),
    Type.Literal("running"),
    Type.Literal("completed"),
    Type.Literal("failed"),
    Type.Literal("cancelled"),
  ], { description: "Optional status filter" })),
  limit: Type.Optional(Type.Number({ description: "Max runs to return (default: 10)" })),
});

export const researchGetParams = Type.Object({
  id: Type.String({ description: "Research run ID" }),
});

export const researchCancelParams = Type.Object({
  id: Type.String({ description: "Research run ID to cancel" }),
});

export const memoryAppendParams = Type.Object({
  scope: Type.Optional(Type.Union([
    Type.Literal("project"),
    Type.Literal("agent"),
  ], { description: "project for workspace memory, agent for this agent's private memory" })),
  layer: Type.Union([
    Type.Literal("long-term"),
    Type.Literal("daily"),
  ], { description: "long-term for durable conventions/decisions/pitfalls, daily for running notes/open loops" }),
  content: Type.String({ description: "Markdown content to append. Keep it concise and reusable." }),
});

type MemoryToolSettings = {
  memoryBackendType?: string;
  [key: string]: unknown;
};

type AgentMemoryContext = {
  agentId: string;
  agentName?: string;
  memory?: string | null;
};

type MemoryToolOptions = {
  agentMemory?: AgentMemoryContext;
};

type MemorySearchHit = {
  path: string;
  lineStart: number;
  lineEnd: number;
  snippet: string;
  score: number;
  backend: string;
};

const log = createLogger("agent-tools");

const MAX_INSTRUCTIONS_TEXT_LENGTH = 50_000;
const MAX_MEMORY_LENGTH = 50_000;
const MAX_SOUL_LENGTH = 10_000;

const AGENT_MEMORY_ROOT = ".fusion/agent-memory";
const AGENT_MEMORY_FILENAME = "MEMORY.md";
const AGENT_DREAMS_FILENAME = "DREAMS.md";
const agentQmdRefreshState = new Map<string, { lastStartedAt: number; inFlight?: Promise<void> }>();
const AGENT_QMD_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
const DAILY_AGENT_MEMORY_RE = /^\d{4}-\d{2}-\d{2}\.md$/;

export function sanitizeAgentMemoryId(agentId: string): string {
  return agentId.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
}

export function agentMemoryDisplayPath(agentId: string): string {
  return `${AGENT_MEMORY_ROOT}/${sanitizeAgentMemoryId(agentId)}/${AGENT_MEMORY_FILENAME}`;
}

function agentDreamsDisplayPath(agentId: string): string {
  return `${AGENT_MEMORY_ROOT}/${sanitizeAgentMemoryId(agentId)}/${AGENT_DREAMS_FILENAME}`;
}

function agentMemoryDirectory(rootDir: string, agentId: string): string {
  return join(rootDir, AGENT_MEMORY_ROOT, sanitizeAgentMemoryId(agentId));
}

export function agentMemoryFilePath(rootDir: string, agentId: string): string {
  return join(agentMemoryDirectory(rootDir, agentId), AGENT_MEMORY_FILENAME);
}

function agentDreamsFilePath(rootDir: string, agentId: string): string {
  return join(agentMemoryDirectory(rootDir, agentId), AGENT_DREAMS_FILENAME);
}

function agentDailyFilePath(rootDir: string, agentId: string, date = new Date()): string {
  return join(agentMemoryDirectory(rootDir, agentId), `${date.toISOString().slice(0, 10)}.md`);
}

export async function readAgentMemoryWorkspaceLongTerm(rootDir: string, agentId: string): Promise<string> {
  const safeRoot = typeof rootDir === "string" ? rootDir.trim() : "";
  const safeAgentId = typeof agentId === "string" ? agentId.trim() : "";
  if (!safeRoot || !safeAgentId) {
    return "";
  }

  const filePath = agentMemoryFilePath(safeRoot, safeAgentId);
  try {
    const fileStat = await stat(filePath);
    if (!fileStat.isFile()) {
      return "";
    }
    const content = await readFile(filePath, "utf-8");
    return typeof content === "string" ? content.trim() : "";
  } catch {
    return "";
  }
}

export function qmdAgentMemoryCollectionName(rootDir: string, agentId: string): string {
  const hash = createHash("sha1").update(`${rootDir}:${agentId}`).digest("hex").slice(0, 12);
  return `fusion-agent-memory-${sanitizeAgentMemoryId(agentId).toLowerCase()}-${hash}`;
}

export function buildQmdAgentMemoryCollectionAddArgs(rootDir: string, agentId: string): string[] {
  return [
    "collection",
    "add",
    agentMemoryDirectory(rootDir, agentId),
    "--name",
    qmdAgentMemoryCollectionName(rootDir, agentId),
    "--mask",
    "**/*.md",
  ];
}

export function buildQmdAgentMemorySearchArgs(rootDir: string, agentId: string, query: string, limit = 5): string[] {
  return [
    "search",
    query,
    "--json",
    "--collection",
    qmdAgentMemoryCollectionName(rootDir, agentId),
    "-n",
    String(Math.max(1, Math.min(limit, 20))),
  ];
}

async function syncAgentMemoryFile(rootDir: string, agentMemory?: AgentMemoryContext): Promise<string | null> {
  const content = agentMemory?.memory?.trim();
  if (!agentMemory?.agentId) {
    return null;
  }

  const dir = agentMemoryDirectory(rootDir, agentMemory.agentId);
  await mkdir(dir, { recursive: true });
  const longTermPath = agentMemoryFilePath(rootDir, agentMemory.agentId);
  if (!existsSync(longTermPath)) {
    const title = agentMemory.agentName?.trim()
      ? `# Agent Memory: ${agentMemory.agentName.trim()}`
      : "# Agent Memory";
    const fileContent = `${title}\n\n<!-- Per-agent memory. Keep separate from workspace Project Memory. -->\n\n${content || ""}\n`;
    await writeFile(longTermPath, fileContent, "utf-8");
  }
  const dreamsPath = agentDreamsFilePath(rootDir, agentMemory.agentId);
  if (!existsSync(dreamsPath)) {
    await writeFile(dreamsPath, "# Agent Memory Dreams\n\n<!-- Synthesized patterns from this agent's daily notes. -->\n", "utf-8");
  }
  const dailyPath = agentDailyFilePath(rootDir, agentMemory.agentId);
  if (!existsSync(dailyPath)) {
    await writeFile(dailyPath, `# Agent Daily Memory ${new Date().toISOString().slice(0, 10)}\n\n<!-- Running observations for this agent. -->\n`, "utf-8");
  }
  return agentMemoryDisplayPath(agentMemory.agentId);
}

async function listAgentMemoryFiles(rootDir: string, agentMemory: AgentMemoryContext): Promise<Array<{ absPath: string; displayPath: string }>> {
  await syncAgentMemoryFile(rootDir, agentMemory);
  const dir = agentMemoryDirectory(rootDir, agentMemory.agentId);
  const files = [
    { absPath: agentMemoryFilePath(rootDir, agentMemory.agentId), displayPath: agentMemoryDisplayPath(agentMemory.agentId) },
    { absPath: agentDreamsFilePath(rootDir, agentMemory.agentId), displayPath: agentDreamsDisplayPath(agentMemory.agentId) },
  ];
  let entries: string[];
  try {
    entries = await readdir(dir);
  } catch (err) {
    log.warn(`Failed to read agent memory directory ${dir}: ${err instanceof Error ? err.message : String(err)}`);
    entries = [];
  }

  for (const entry of entries) {
    if (!DAILY_AGENT_MEMORY_RE.test(entry)) continue;
    const absPath = join(dir, entry);
    const fileStat = await stat(absPath);
    if (fileStat.isFile()) {
      files.push({
        absPath,
        displayPath: `${AGENT_MEMORY_ROOT}/${sanitizeAgentMemoryId(agentMemory.agentId)}/${entry}`,
      });
    }
  }
  return files;
}

function scoreAgentMemorySnippet(snippet: string, query: string): number {
  const terms = query.toLowerCase().split(/[^a-z0-9_-]+/i).filter((term) => term.length >= 2);
  const normalized = snippet.toLowerCase();
  return terms.reduce((score, term) => score + (normalized.includes(term) ? 1 : 0), 0);
}

async function searchAgentMemoryFile(rootDir: string, agentMemory: AgentMemoryContext, query: string, limit: number): Promise<MemorySearchHit[]> {
  const displayPath = await syncAgentMemoryFile(rootDir, agentMemory);
  if (!displayPath) {
    return [];
  }

  const results: MemorySearchHit[] = [];
  for (const file of await listAgentMemoryFiles(rootDir, agentMemory)) {
    const content = await readFile(file.absPath, "utf-8");
    const lines = content.split("\n");
    for (let index = 0; index < lines.length; index += 8) {
      const chunk = lines.slice(index, index + 12).join("\n").trim();
      if (!chunk) continue;
      const score = scoreAgentMemorySnippet(chunk, query);
      if (score === 0) continue;
      results.push({
        path: file.displayPath,
        lineStart: index + 1,
        lineEnd: Math.min(index + 12, lines.length),
        snippet: chunk.slice(0, 1200),
        score: score + 1000,
        backend: "agent-memory",
      });
    }
  }
  return results.slice(0, limit);
}

async function refreshAgentMemoryQmdIndex(rootDir: string, agentMemory: AgentMemoryContext): Promise<void> {
  if (shouldSkipBackgroundQmdRefresh()) {
    return;
  }
  await syncAgentMemoryFile(rootDir, agentMemory);
  const key = `${rootDir}:${agentMemory.agentId}`;
  const now = Date.now();
  const current = agentQmdRefreshState.get(key);
  if (current?.inFlight) {
    return current.inFlight;
  }
  if (current && now - current.lastStartedAt < AGENT_QMD_REFRESH_INTERVAL_MS) {
    return;
  }

  const promise = (async () => {
    const { execFile } = await import("node:child_process");
    const { promisify } = await import("node:util");
    const execFileAsync = promisify(execFile);
    try {
      await execFileAsync("qmd", buildQmdAgentMemoryCollectionAddArgs(rootDir, agentMemory.agentId), {
        cwd: rootDir,
        timeout: 4000,
        maxBuffer: 512 * 1024,
      });
    } catch (error: unknown) {
      const message = error instanceof Error ? error.message : String(error);
      const stderr = typeof error === "object" && error && "stderr" in error ? String((error as { stderr?: unknown }).stderr ?? "") : "";
      if (!/already exists|exists/i.test(`${message}\n${stderr}`)) {
        throw error;
      }
    }
    await execFileAsync("qmd", ["update"], { cwd: rootDir, timeout: 30_000, maxBuffer: 1024 * 1024 });
    await execFileAsync("qmd", ["embed"], { cwd: rootDir, timeout: 120_000, maxBuffer: 1024 * 1024 });
  })();

  agentQmdRefreshState.set(key, { lastStartedAt: now, inFlight: promise });
  try {
    await promise;
  } finally {
    const latest = agentQmdRefreshState.get(key);
    if (latest?.inFlight === promise) {
      agentQmdRefreshState.set(key, { lastStartedAt: latest.lastStartedAt });
    }
  }
}

function normalizeQmdAgentMemoryResultPath(rootDir: string, agentId: string, rawPath: unknown): string {
  const fallbackPath = agentMemoryDisplayPath(agentId);
  const original = String(rawPath ?? "").trim();
  if (!original) {
    return fallbackPath;
  }

  let candidate = original.replace(/\\/g, "/");
  const uriMatch = candidate.match(/^qmd:\/\/[^/]+\/(.+)$/i);
  if (uriMatch?.[1]) {
    candidate = uriMatch[1];
  }

  candidate = candidate.split("?")[0]?.split("#")[0] ?? "";
  candidate = candidate.replace(/^\.\/+/, "");

  const normalizedAgentId = sanitizeAgentMemoryId(agentId);
  const agentPrefix = `${AGENT_MEMORY_ROOT}/${normalizedAgentId}/`;
  if (candidate.startsWith(agentPrefix)) {
    return resolveAgentMemoryPath(rootDir, agentId, candidate)?.displayPath ?? fallbackPath;
  }

  const workspacePath = resolve(agentMemoryDirectory(rootDir, agentId)).replace(/\\/g, "/");
  const candidateAbs = resolve(rootDir, candidate).replace(/\\/g, "/");
  const relToWorkspace = relative(workspacePath, candidateAbs).replace(/\\/g, "/");
  if (relToWorkspace && !relToWorkspace.startsWith("..") && !relToWorkspace.includes("/../")) {
    const maybeDisplayPath = `${agentPrefix}${relToWorkspace}`;
    return resolveAgentMemoryPath(rootDir, agentId, maybeDisplayPath)?.displayPath ?? fallbackPath;
  }

  const filename = candidate.split("/").pop() ?? "";
  if (filename.toLowerCase() === AGENT_MEMORY_FILENAME.toLowerCase()) {
    return agentMemoryDisplayPath(agentId);
  }
  if (filename.toLowerCase() === AGENT_DREAMS_FILENAME.toLowerCase()) {
    return agentDreamsDisplayPath(agentId);
  }
  if (DAILY_AGENT_MEMORY_RE.test(filename)) {
    return `${agentPrefix}${filename}`;
  }

  return fallbackPath;
}

async function searchAgentMemoryWithQmd(rootDir: string, agentMemory: AgentMemoryContext, query: string, limit: number): Promise<MemorySearchHit[]> {
  if (shouldSkipBackgroundQmdRefresh()) {
    return searchAgentMemoryFile(rootDir, agentMemory, query, limit);
  }
  try {
    await refreshAgentMemoryQmdIndex(rootDir, agentMemory);
    const { execFile } = await import("node:child_process");
    const { promisify } = await import("node:util");
    const execFileAsync = promisify(execFile);
    const { stdout } = await execFileAsync("qmd", buildQmdAgentMemorySearchArgs(rootDir, agentMemory.agentId, query, limit), {
      cwd: rootDir,
      timeout: 4000,
      maxBuffer: 1024 * 1024,
    });
    const parsed = JSON.parse(stdout);
    const rawResults = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.results) ? parsed.results : [];
    return rawResults.slice(0, limit).map((result: Record<string, unknown>) => {
      const rawPath = result.path ?? result.file;
      return {
        path: normalizeQmdAgentMemoryResultPath(rootDir, agentMemory.agentId, rawPath),
        lineStart: Number(result.lineStart ?? result.startLine ?? 1),
        lineEnd: Number(result.lineEnd ?? result.endLine ?? result.startLine ?? 1),
        snippet: String(result.snippet ?? result.text ?? result.content ?? "").slice(0, 1200),
        score: Number(result.score ?? 1) + 1000,
        backend: "qmd-agent-memory",
      };
    }).filter((result: MemorySearchHit) => result.snippet.trim().length > 0);
  } catch (err) {
    log.warn(
      `QMD agent memory search failed for agent ${agentMemory.agentId}, falling back to file search: ${err instanceof Error ? err.message : String(err)}`,
    );
    return searchAgentMemoryFile(rootDir, agentMemory, query, limit);
  }
}

function resolveAgentMemoryPath(rootDir: string, agentId: string, path: string): { absPath: string; displayPath: string } | null {
  const safeAgentId = sanitizeAgentMemoryId(agentId);
  const prefix = `${AGENT_MEMORY_ROOT}/${safeAgentId}/`;
  if (!path.startsWith(prefix)) {
    return null;
  }
  const filename = path.slice(prefix.length);
  if (filename !== AGENT_MEMORY_FILENAME && filename !== AGENT_DREAMS_FILENAME && !DAILY_AGENT_MEMORY_RE.test(filename)) {
    return null;
  }
  return {
    absPath: join(agentMemoryDirectory(rootDir, agentId), filename),
    displayPath: `${prefix}${filename}`,
  };
}

async function getAgentMemoryWindow(rootDir: string, agentMemory: AgentMemoryContext, path: string, startLine = 1, lineCount = 40) {
  const resolved = resolveAgentMemoryPath(rootDir, agentMemory.agentId, path);
  if (!resolved) {
    return null;
  }
  await syncAgentMemoryFile(rootDir, agentMemory);
  const content = await readFile(resolved.absPath, "utf-8");
  const lines = content.split("\n");
  const start = Math.max(1, Math.floor(startLine));
  const count = Math.max(1, Math.min(Math.floor(lineCount), 200));
  const startIndex = Math.min(start - 1, lines.length);
  const endIndex = Math.min(startIndex + count, lines.length);
  return {
    path: resolved.displayPath,
    content: lines.slice(startIndex, endIndex).join("\n"),
    startLine: start,
    endLine: endIndex,
    totalLines: lines.length,
    backend: "agent-memory",
  };
}

// ── Tool factory functions ────────────────────────────────────────────────

type AgentTaskCreationOptions = {
  rootDir?: string;
  bypassDuplicateCheck?: boolean;
  acknowledgedDuplicates?: string[];
};

export async function createAgentTask(
  store: TaskStore,
  input: TaskCreateInput,
  options?: AgentTaskCreationOptions,
): Promise<{ task: Awaited<ReturnType<TaskStore["createTask"]>>; wasDuplicate: boolean }> {
  const settings = typeof (store as { getSettings?: unknown }).getSettings === "function"
    ? await store.getSettings()
    : {} as Settings;
  const rootDir = options?.rootDir;
  const guard = await runDeterministicDuplicateGuard(store, {
    title: input.title,
    description: input.description,
  }, {
    lockScope: rootDir ?? store.getRootDir?.() ?? "agent-tools",
    bypass: options?.bypassDuplicateCheck === true,
    acknowledgedDuplicates: options?.acknowledgedDuplicates,
    logger: log,
  });

  try {
    if (guard.action === "duplicate" && guard.existing) {
      return { task: guard.existing, wasDuplicate: true };
    }

    const sourceMetadata = {
      ...(input.source?.sourceMetadata ?? {}),
      ...(guard.fingerprint ? { contentFingerprint: guard.fingerprint } : {}),
    };
    const nextSource = input.source
      ? {
          ...input.source,
          sourceMetadata: Object.keys(sourceMetadata).length > 0 ? sourceMetadata : undefined,
        }
      : undefined;

    const globalSettings =
      (await store.getGlobalSettingsStore?.()?.getSettings?.()) ?? {};
    const resolvedTracking = resolveTaskGithubTracking(
      { githubTracking: input.githubTracking },
      settings,
      globalSettings,
    );

    const shouldPrefillGithubTrackingEnabled =
      input.githubTracking?.enabled !== false && resolvedTracking.enabled;
    const createInput: TaskCreateInput = {
      ...input,
      source: nextSource,
      githubTracking: shouldPrefillGithubTrackingEnabled
        ? {
            ...(input.githubTracking ?? {}),
            enabled: true,
            ...(input.githubTracking?.repoOverride || !resolvedTracking.repo
              ? {}
              : { repoOverride: `${resolvedTracking.repo.owner}/${resolvedTracking.repo.repo}` }),
          }
        : input.githubTracking,
    };

    const createdTask = await store.createTask(createInput, {
      settings: { autoSummarizeTitles: settings.autoSummarizeTitles === true },
      onSummarize: rootDir
        ? async (description: string) => {
          const resolved = resolveTitleSummarizerSettingsModel(settings);
          return summarizeTitle(description, rootDir, resolved.provider, resolved.modelId);
        }
        : undefined,
    });

    const reconcile = await reconcileDeterministicDuplicate(store, {
      createdTask,
      fingerprint: guard.fingerprint,
      logger: log,
    });

    return { task: reconcile.canonical, wasDuplicate: reconcile.outcome === "archived" };
  } finally {
    guard.releaseLock();
  }
}

/**
 * Create a `fn_task_create` tool that creates a new task in triage.
 *
 * @param store - TaskStore for task persistence
 * @returns ToolDefinition for the `fn_task_create` tool
 */
export function createTaskCreateTool(
  store: TaskStore,
  provenance?: { sourceType: SourceType; sourceAgentId?: string; sourceRunId?: string; sourceParentTaskId?: string },
  options?: AgentTaskCreationOptions,
): ToolDefinition {
  return {
    name: "fn_task_create",
    label: "Create Task",
    description:
      "Create a new task for out-of-scope work discovered during execution. " +
      "The task goes into triage where it will be specified by the AI. " +
      "Before creating, scan existing open tasks for similar work — if an open task " +
      "already covers this, do not create a duplicate. " +
      "Optionally set dependencies (e.g., the new task depends on the current one, " +
      "or the current task should wait for the new one).",
    parameters: taskCreateParams,
    execute: async (_id: string, params: Static<typeof taskCreateParams>) => {
      try {
        const { task, wasDuplicate } = await createAgentTask(store, {
          description: params.description,
          dependencies: params.dependencies,
          column: "triage",
          priority: params.priority,
          source: provenance ? {
            sourceType: provenance.sourceType,
            sourceAgentId: provenance.sourceAgentId,
            sourceRunId: provenance.sourceRunId,
            sourceParentTaskId: provenance.sourceParentTaskId,
          } : undefined,
        }, options);
        const deps = task.dependencies.length ? ` (depends on: ${task.dependencies.join(", ")})` : "";
        return {
          content: [{
            type: "text" as const,
            text: `${wasDuplicate ? "Linked existing" : "Created"} ${task.id}: ${params.description}${deps}`,
          }],
          details: { taskId: task.id },
        };
      } catch (err) {
        if (err instanceof Error && err.message.startsWith("Task ID already exists:")) {
          return {
            content: [{ type: "text" as const, text: `ERROR: ${err.message}` }],
            details: {},
            isError: true,
          };
        }
        if (err instanceof Error && (err as { code?: string }).code === "SELF_DEFEATING_DEPENDENCY") {
          return {
            content: [{ type: "text" as const, text: `ERROR: ${err.message}` }],
            details: {},
            isError: true,
          };
        }
        throw err;
      }
    },
  };
}

/**
 * Create a `fn_task_log` tool that logs an entry for a specific task.
 *
 * @param store - TaskStore for task persistence
 * @param taskId - The task ID to log entries against
 * @returns ToolDefinition for the `fn_task_log` tool
 */
export function createTaskLogTool(store: TaskStore, taskId: string): ToolDefinition {
  return {
    name: "fn_task_log",
    label: "Log Entry",
    description:
      "Log an important action, decision, or issue for this task. " +
      "Use for significant events — not every small step.",
    parameters: taskLogParams,
    execute: async (_id: string, params: Static<typeof taskLogParams>) => {
      try {
        await store.logEntry(taskId, params.message, params.outcome);
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        if (typeof err?.message === "string" && err.message.toLowerCase().includes("archived")) {
          return {
            content: [{ type: "text" as const, text: "ERROR: Cannot log to archived task — this task is read-only" }],
            details: {},
          };
        }
        throw err;
      }

      return {
        content: [{ type: "text" as const, text: `Logged: ${params.message}` }],
        details: {},
      };
    },
  };
}

/**
 * Create a `fn_task_log` tool with run context for mutation correlation.
 *
 * @param store - TaskStore for task persistence
 * @param taskId - The task ID to log entries against
 * @param runContext - Optional run context for mutation correlation
 * @returns ToolDefinition for the `fn_task_log` tool
 */
export function createTaskLogToolWithContext(store: TaskStore, taskId: string, runContext?: RunMutationContext): ToolDefinition {
  return {
    name: "fn_task_log",
    label: "Log Entry",
    description:
      "Log an important action, decision, or issue for this task. " +
      "Use for significant events — not every small step.",
    parameters: taskLogParams,
    execute: async (_id: string, params: Static<typeof taskLogParams>) => {
      try {
        await store.logEntry(taskId, params.message, params.outcome, runContext);
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        if (typeof err?.message === "string" && err.message.toLowerCase().includes("archived")) {
          return {
            content: [{ type: "text" as const, text: "ERROR: Cannot log to archived task — this task is read-only" }],
            details: {},
          };
        }
        throw err;
      }

      return {
        content: [{ type: "text" as const, text: `Logged: ${params.message}` }],
        details: {},
      };
    },
  };
}

/**
 * Create a `fn_task_document_write` tool that stores a named task document.
 *
 * @param store - TaskStore for task document persistence
 * @param taskId - The task ID to write documents against
 * @returns ToolDefinition for the `fn_task_document_write` tool
 */
export function createTaskDocumentWriteTool(store: TaskStore, taskId: string): ToolDefinition {
  return {
    name: "fn_task_document_write",
    label: "Write Document",
    description:
      "Save a named document for this task (for example plan, notes, or research). " +
      "Each write creates a new revision so you can update documents over time.",
    parameters: taskDocumentWriteParams,
    execute: async (_id: string, params: Static<typeof taskDocumentWriteParams>) => {
      const input: TaskDocumentCreateInput = {
        key: params.key,
        content: params.content,
        author: params.author || "agent",
      };

      try {
        const document: TaskDocument = await store.upsertTaskDocument(taskId, input);
        return {
          content: [{
            type: "text" as const,
            text: `Saved document "${document.key}" (revision ${document.revision}).`,
          }],
          details: {},
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{
            type: "text" as const,
            text: `ERROR: Failed to save document "${params.key}": ${err.message}`,
          }],
          details: {},
        };
      }
    },
  };
}

/**
 * Create a `fn_task_document_read` tool that reads task-scoped documents.
 *
 * @param store - TaskStore for task document reads
 * @param taskId - The task ID to read documents from
 * @returns ToolDefinition for the `fn_task_document_read` tool
 */
export function createTaskDocumentReadTool(store: TaskStore, taskId: string): ToolDefinition {
  return {
    name: "fn_task_document_read",
    label: "Read Document",
    description:
      "Read a named document for this task, or list all documents when no key is provided.",
    parameters: taskDocumentReadParams,
    execute: async (_id: string, params: Static<typeof taskDocumentReadParams>) => {
      try {
        if (params.key) {
          const document: TaskDocument | null = await store.getTaskDocument(taskId, params.key);
          if (!document) {
            return {
              content: [{ type: "text" as const, text: `Document "${params.key}" not found.` }],
              details: {},
            };
          }

          return {
            content: [{
              type: "text" as const,
              text:
                `Document: ${document.key}\n` +
                `Revision: ${document.revision}\n` +
                `Updated: ${document.updatedAt}\n\n` +
                document.content,
            }],
            details: {},
          };
        }

        const documents: TaskDocument[] = await store.getTaskDocuments(taskId);
        if (documents.length === 0) {
          return {
            content: [{ type: "text" as const, text: "No documents found for this task." }],
            details: {},
          };
        }

        const lines = documents.map((doc) => `- ${doc.key} (revision ${doc.revision}, updated ${doc.updatedAt})`);
        return {
          content: [{
            type: "text" as const,
            text: `Task documents:\n${lines.join("\n")}`,
          }],
          details: {},
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{
            type: "text" as const,
            text: `ERROR: Failed to read task documents: ${err.message}`,
          }],
          details: {},
        };
      }
    },
  };
}

/**
 * Create a `fn_workflow_list` tool that lists the workflows available for a
 * project (read-only built-ins plus user-authored definitions). Agent-native
 * parity with the dashboard's workflow picker.
 */
export function createWorkflowListTool(store: TaskStore): ToolDefinition {
  return {
    name: "fn_workflow_list",
    label: "List Workflows",
    description:
      "List the custom workflows available for this project — read-only built-ins " +
      "(ids starting with 'builtin:') and user-authored definitions. Use before " +
      "fn_workflow_select to discover valid workflow IDs.",
    parameters: workflowListParams,
    execute: async () => {
      try {
        const workflows = await store.listWorkflowDefinitions();
        if (workflows.length === 0) {
          return {
            content: [{ type: "text" as const, text: "No workflows are defined for this project." }],
            details: {},
          };
        }
        const lines = workflows.map(
          (w) => `- ${w.id}: ${w.name}${w.description ? ` — ${w.description}` : ""}`,
        );
        return {
          content: [{ type: "text" as const, text: `Available workflows:\n${lines.join("\n")}` }],
          details: { workflowIds: workflows.map((w) => w.id) },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to list workflows: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_workflow_get` tool that returns a single workflow definition by
 * id — id/name/description, whether it is a read-only built-in, and the full
 * resolved IR (nodes/edges/columns/artifacts/fields) as JSON. Agent-native
 * read parity with the dashboard's workflow inspector; the companion read tool
 * to fn_workflow_list. Read-only; an unknown id is reported as a tool error.
 */
export function createWorkflowGetTool(store: TaskStore): ToolDefinition {
  return {
    name: "fn_workflow_get",
    label: "Get Workflow",
    description:
      "Fetch a single workflow definition by its ID — its name, description, whether it is a " +
      "read-only built-in, and its full IR (nodes, edges, columns, artifacts, and custom fields) " +
      "as JSON. Use fn_workflow_list to discover IDs first.",
    parameters: workflowGetParams,
    execute: async (_id: string, params: Static<typeof workflowGetParams>) => {
      const workflowId = params.workflow_id?.trim();
      if (!workflowId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: workflow_id is required." }],
          details: {},
          isError: true,
        };
      }
      try {
        const def = await store.getWorkflowDefinition(workflowId);
        if (!def) {
          return {
            content: [{ type: "text" as const, text: `ERROR: Unknown workflow id '${workflowId}'. Use fn_workflow_list to discover valid IDs.` }],
            details: {},
            isError: true,
          };
        }
        const builtin = isBuiltinWorkflowId(def.id);
        const payload = {
          id: def.id,
          name: def.name,
          description: def.description,
          builtin,
          ir: def.ir,
          // Preserve editor node positions so a read→modify→write cycle does not
          // strip the layout. May be absent for older/built-in defs; only include
          // when present to keep the payload tidy.
          ...(def.layout ? { layout: def.layout } : {}),
        };
        return {
          content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
          details: { workflowId: def.id, builtin, ...(def.layout ? { layout: def.layout } : {}) },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to get workflow: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_workflow_select` tool that assigns a workflow definition to a
 * task (defaulting to the current task). Mirrors the dashboard's per-task
 * workflow selection so an agent can set up a task the same way a user can.
 */
export function createWorkflowSelectTool(store: TaskStore, currentTaskId: string): ToolDefinition {
  return {
    name: "fn_workflow_select",
    label: "Select Workflow",
    description:
      "Assign a custom workflow to a task by its workflow ID. Defaults to the " +
      "current task when task_id is omitted. Note: selecting a workflow does not " +
      "retroactively change a pipeline already running — it applies when the task " +
      "next executes its steps. Use fn_workflow_list to find valid IDs.",
    parameters: workflowSelectParams,
    execute: async (_id: string, params: Static<typeof workflowSelectParams>) => {
      const taskId = params.task_id?.trim() || currentTaskId;
      try {
        const { enabledWorkflowSteps: enabled, reconciliation } =
          await store.selectTaskWorkflowAndReconcile(taskId, params.workflow_id);
        const stepSummary = `${enabled.length} step${enabled.length === 1 ? "" : "s"} enabled`;
        // Surface the reconciliation outcome so the agent observes any re-home:
        // a preserved card stays put; an unpreserved card moves fromColumn→toColumn.
        const rehomeNote =
          reconciliation && !reconciliation.preserved && reconciliation.fromColumn !== reconciliation.toColumn
            ? ` Re-homed from '${reconciliation.fromColumn}' to '${reconciliation.toColumn}'.`
            : reconciliation
              ? ` Card preserved in '${reconciliation.toColumn}'.`
              : "";
        return {
          content: [{
            type: "text" as const,
            text: `Selected workflow ${params.workflow_id} for ${taskId} (${stepSummary}).${rehomeNote}`,
          }],
          details: { taskId, workflowId: params.workflow_id, enabledWorkflowSteps: enabled, reconciliation },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to select workflow: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_task_promote` tool that manually releases a held task out of its
 * hold column — the agent-native equivalent of the dashboard's "promote" action.
 * Defaults to the current task. Wraps {@link promoteHeldTask}.
 */
export function createTaskPromoteTool(store: TaskStore, currentTaskId: string): ToolDefinition {
  return {
    name: "fn_task_promote",
    label: "Promote Held Task",
    description:
      "Manually promote a held task out of its hold column, releasing it regardless of the " +
      "hold's release kind (the explicit operator action a 'manual' hold waits for). Defaults " +
      "to the current task. Returns the destination column, or a rejection reason when the task " +
      "is not held or the destination is full.",
    parameters: taskPromoteParams,
    execute: async (_id: string, params: Static<typeof taskPromoteParams>) => {
      const taskId = params.task_id?.trim() || currentTaskId;
      try {
        const outcome = await promoteHeldTask(store, taskId);
        if (outcome.released) {
          return {
            content: [{
              type: "text" as const,
              text: `Promoted ${taskId} to column '${outcome.toColumn}'.`,
            }],
            details: { taskId, released: true, toColumn: outcome.toColumn },
          };
        }
        return {
          content: [{
            type: "text" as const,
            text: `ERROR: Could not promote ${taskId}: ${outcome.rejection ?? "unknown"}.`,
          }],
          details: { taskId, released: false, rejection: outcome.rejection },
          isError: true,
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to promote task: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Shared write-time column-agent gate for the `fn_workflow_*` tools (R11/R13).
 * Runs the SAME `validateColumnAgentBindings` check the dashboard route runs, so
 * an agent cannot persist a binding the UI would reject (existence +
 * policy-escalation). Constructs a per-call AgentStore from the store's fusion
 * dir (the connection is process-cached) and feeds it the project settings.
 *
 * A {@link ColumnAgentBindingError} propagates unchanged; each tool's catch
 * surfaces its message (which names the column and, for an escalation, instructs
 * passing `confirm_policy_escalation: true`).
 */
async function assertWorkflowColumnAgentBindings(
  store: TaskStore,
  ir: unknown,
  confirmPolicyEscalation: boolean,
): Promise<void> {
  const columns = (ir as { columns?: unknown })?.columns;
  if (!Array.isArray(columns) || !columns.some((c) => c?.agent?.agentId)) return;
  const agentStore = new AgentStore({ rootDir: store.getFusionDir() });
  await agentStore.init();
  const settings = await store.getSettings();
  await validateColumnAgentBindings({ ir, agentStore, settings, confirmPolicyEscalation });
}

/**
 * Render a {@link ColumnAgentBindingError} as a structured tool error result.
 * Re-phrases the escalation guidance with the tool's snake_case flag name
 * (`confirm_policy_escalation`) rather than the route's camelCase variant.
 */
function columnAgentBindingErrorResult(err: ColumnAgentBindingError) {
  const text =
    err.reason === "policy-escalation"
      ? `Column '${err.columnId}' binds agent '${err.agentId}' whose permission policy is broader than ` +
        `the project default; pass confirm_policy_escalation: true to confirm.`
      : err.message;
  return {
    content: [{ type: "text" as const, text: `ERROR: ${text}` }],
    details: { columnId: err.columnId, agentId: err.agentId, reason: err.reason },
    isError: true as const,
  };
}

/**
 * Create a `fn_workflow_create` tool — a thin wrapper over the store's workflow
 * definition create. The IR is validated server-side; a malformed graph rejects.
 */
export function createWorkflowCreateTool(
  store: TaskStore,
  opts?: WorkflowAuthoringToolOptions,
): ToolDefinition {
  return {
    name: "fn_workflow_create",
    label: "Create Workflow",
    description:
      "Create a new custom workflow definition from a name and a workflow graph (IR). " +
      "The IR is validated server-side; a malformed graph rejects. Returns the new workflow ID.\n" +
      "v2 IR supports step-inversion constructs (all additive, opt-in): " +
      "`parse-steps` node {artifact, parser} writes the task step list from a declared artifact " +
      "(built-in parsers: `step-headings`, `json-steps`; routable `no-steps`/`parse-error` outcomes) — " +
      "it must precede any `foreach`; " +
      "`foreach` node {source:'task-steps', template:{nodes,edges}, mode:'sequential'|'parallel', " +
      "isolation:'shared'|'worktree', concurrency (parallel only, 1-8), maxReworkCycles (1-10)} " +
      "instantiates its single-entry/exit template subgraph once per planned step " +
      "(parallel+shared is rejected); a `step-execute` node is legal only inside a foreach template; " +
      "`step-review` node {type:'plan'|'code', model?} surfaces verdicts as outcome edges " +
      "(`outcome:approve|revise|rethink|unavailable`); edges may set `kind:'rework'` (the only legal cycles, " +
      "back to step-execute within an instance; rethink edges trigger a reset-to-baseline); " +
      "`code` node {source, timeoutMs?} runs sandboxed TypeScript returning {outcome?, contextPatch?, customFields?}. " +
      "Declare task documents via `artifacts: [{key, title?, producedBy?, role?}]` and custom task fields via " +
      "`fields: [{id, name, type, required?, default?, options?, render?}]` (types: string/text/number/boolean/" +
      "enum/multi-enum/date/url; render.placement card|detail|detail-section, render.badge for card chips).\n" +
      "Bind a column to a permanent agent via `columns[].agent: { agentId, mode }`: `mode:'defer'` applies the " +
      "column agent only when the work carries no own agent/model settings, while `mode:'override'` supersedes " +
      "node/task settings wholesale. The bound agent must exist; if its permission policy is broader than the " +
      "project default, pass `confirm_policy_escalation: true` to confirm (the create is otherwise rejected).",
    parameters: workflowCreateParams,
    execute: async (_id: string, params: Static<typeof workflowCreateParams>) => {
      try {
        let approvalNote = "";
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        let ir = params.ir as any;
        if (opts?.stripApprovalFlags) {
          const result = stripApprovalBypassFlags(ir);
          ir = result.ir;
          if (result.stripped) approvalNote = " (approval-bypass flags removed)";
        }
        await assertWorkflowColumnAgentBindings(store, ir, params.confirm_policy_escalation === true);
        const created = await store.createWorkflowDefinition({
          name: params.name,
          description: params.description,
          ir,
          // eslint-disable-next-line @typescript-eslint/no-explicit-any
          layout: params.layout as any,
        });
        return {
          content: [{ type: "text" as const, text: `Created workflow ${created.id} (${created.name}).${approvalNote}` }],
          details: { workflowId: created.id, name: created.name },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        if (err instanceof ColumnAgentBindingError) {
          return columnAgentBindingErrorResult(err);
        }
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to create workflow: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_workflow_update` tool — a thin wrapper over the store's workflow
 * definition update. When an IR change removes a still-occupied column, the store
 * throws an OccupiedColumnsError; we surface it as a structured response carrying
 * the per-column occupant counts so the agent can retry with `rehome_to`.
 */
export function createWorkflowUpdateTool(
  store: TaskStore,
  opts?: WorkflowAuthoringToolOptions,
): ToolDefinition {
  return {
    name: "fn_workflow_update",
    label: "Update Workflow",
    description:
      "Update a custom workflow definition (name/description/ir/layout). Built-ins cannot be edited. " +
      "If an IR change removes a column that still holds cards, the update is blocked and returns the " +
      "occupied columns — retry with rehome_to set to a column id that survives in the new IR. " +
      "The IR accepts the same step-inversion constructs as fn_workflow_create (foreach with mode/isolation/" +
      "concurrency, step-execute, step-review, parse-steps, code nodes, rework edges, artifacts, fields). " +
      "Editing `fields` orphans (never destroys) existing task values for removed/incompatible fields.\n" +
      "Bind a column to a permanent agent via `columns[].agent: { agentId, mode }`: `mode:'defer'` applies the " +
      "column agent only when the work carries no own agent/model settings, while `mode:'override'` supersedes " +
      "node/task settings wholesale. The bound agent must exist; if its permission policy is broader than the " +
      "project default, pass `confirm_policy_escalation: true` to confirm (the update is otherwise rejected).",
    parameters: workflowUpdateParams,
    execute: async (_id: string, params: Static<typeof workflowUpdateParams>) => {
      try {
        let approvalNote = "";
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        let ir = params.ir as any;
        if (ir !== undefined && ir !== null) {
          if (opts?.stripApprovalFlags) {
            const result = stripApprovalBypassFlags(ir);
            ir = result.ir;
            if (result.stripped) approvalNote = " (approval-bypass flags removed)";
          }
          await assertWorkflowColumnAgentBindings(store, ir, params.confirm_policy_escalation === true);
        }
        const updated = await store.updateWorkflowDefinition(params.workflow_id, {
          name: params.name,
          description: params.description,
          ir,
          // eslint-disable-next-line @typescript-eslint/no-explicit-any
          layout: params.layout as any,
          rehomeTo: params.rehome_to,
        });
        return {
          content: [{ type: "text" as const, text: `Updated workflow ${updated.id} (${updated.name}).${approvalNote}` }],
          details: { workflowId: updated.id, name: updated.name },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        if (err instanceof ColumnAgentBindingError) {
          return columnAgentBindingErrorResult(err);
        }
        // Surface the typed OccupiedColumnsError as a structured, retryable result.
        if (err?.name === "OccupiedColumnsError") {
          const occupancies = err.occupancies ?? [];
          // eslint-disable-next-line @typescript-eslint/no-explicit-any
          const summary = occupancies.map((o: any) => `${o.columnId} (${o.count})`).join(", ");
          return {
            content: [{
              type: "text" as const,
              text:
                `ERROR: Update removes occupied column(s): ${summary}. ` +
                `Retry with rehome_to set to a surviving column id.`,
            }],
            details: { occupiedColumns: occupancies, workflowId: err.workflowId, retryWith: "rehome_to" },
            isError: true,
          };
        }
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to update workflow: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_workflow_delete` tool — a thin wrapper over the store's workflow
 * definition delete. Surfaces built-in protection and not-found errors as
 * structured responses. (The store auto-re-homes occupants to the default
 * workflow on delete, so no rehome target is required here.)
 */
export function createWorkflowDeleteTool(store: TaskStore): ToolDefinition {
  return {
    name: "fn_workflow_delete",
    label: "Delete Workflow",
    description:
      "Delete a custom workflow definition. Built-ins cannot be deleted. Any tasks using it have " +
      "their selection cleared and are re-homed to the default workflow's entry column.",
    parameters: workflowDeleteParams,
    execute: async (_id: string, params: Static<typeof workflowDeleteParams>) => {
      try {
        await store.deleteWorkflowDefinition(params.workflow_id);
        return {
          content: [{ type: "text" as const, text: `Deleted workflow ${params.workflow_id}.` }],
          details: { workflowId: params.workflow_id },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        if (err?.name === "OccupiedColumnsError") {
          const occupancies = err.occupancies ?? [];
          // eslint-disable-next-line @typescript-eslint/no-explicit-any
          const summary = occupancies.map((o: any) => `${o.columnId} (${o.count})`).join(", ");
          return {
            content: [{
              type: "text" as const,
              text: `ERROR: Delete blocked by occupied column(s): ${summary}.`,
            }],
            details: { occupiedColumns: occupancies, workflowId: err.workflowId },
            isError: true,
          };
        }
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to delete workflow: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Create a `fn_trait_list` tool that returns the trait catalog from
 * {@link listTraits} — the column-behavior building blocks (id, name, flags)
 * used when authoring workflow columns.
 */
export function createTraitListTool(): ToolDefinition {
  return {
    name: "fn_trait_list",
    label: "List Traits",
    description:
      "List the available column traits (the behavior building blocks for workflow columns): " +
      "id, name, description, and behavior flags. Use when authoring or updating a workflow IR.",
    parameters: traitListParams,
    execute: async () => {
      try {
        const traits = listTraits();
        if (traits.length === 0) {
          return {
            content: [{ type: "text" as const, text: "No traits are registered." }],
            details: { traits: [] },
          };
        }
        const lines = traits.map(
          (t) => `- ${t.id}: ${t.name}${t.description ? ` — ${t.description}` : ""}`,
        );
        return {
          content: [{ type: "text" as const, text: `Available traits:\n${lines.join("\n")}` }],
          details: {
            traits: traits.map((t) => ({ id: t.id, name: t.name, description: t.description, flags: t.flags })),
          },
        };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to list traits: ${err?.message ?? err}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

/**
 * Assemble the full workflow-authoring tool surface for a single store-scoped
 * lane (chat / planning / executor): the six `fn_workflow_*` tools plus
 * `fn_trait_list` (trait vocabulary needed to author/update workflow IR).
 *
 * Centralizing the list keeps the chat and planning lanes from drifting away
 * from the executor's set as new workflow tools are added. `currentTaskId` is
 * the default task for `fn_workflow_select`; lanes with no ambient task pass a
 * placeholder (an agent can still target any task via the `task_id` param).
 */
/**
 * Options for the workflow authoring tool set.
 *
 * `stripApprovalFlags` removes the `cliSkipApproval`/`autoApprove` approval-
 * bypass flags from every node config (incl. nested foreach templates) before
 * the create/update tools persist the IR. Chat and planning lanes are prompt-
 * injectable, so they pass `true`; the executor lane (project-owner escape
 * hatch) omits it so the dashboard editor can deliberately set those flags.
 */
export interface WorkflowAuthoringToolOptions {
  stripApprovalFlags?: boolean;
}

export function createWorkflowAuthoringTools(
  store: TaskStore,
  currentTaskId: string,
  opts?: WorkflowAuthoringToolOptions,
): ToolDefinition[] {
  return [
    createWorkflowListTool(store),
    createWorkflowGetTool(store),
    createWorkflowSelectTool(store, currentTaskId),
    createWorkflowCreateTool(store, opts),
    createWorkflowUpdateTool(store, opts),
    createWorkflowDeleteTool(store),
    createTraitListTool(),
  ];
}

export function createMemorySearchTool(rootDir: string, settings?: MemoryToolSettings, options?: MemoryToolOptions): ToolDefinition {
  return {
    name: "fn_memory_search",
    label: "Search Memory",
    description:
      "Search durable project memory and this agent's own memory, returning small snippets with file paths and line ranges. " +
      "Use this before fn_memory_get; do not read all memory by default.",
    parameters: memorySearchParams,
    execute: async (_id: string, params: Static<typeof memorySearchParams>) => {
      const limit = params.limit ?? 5;
      const agentResults = options?.agentMemory
        ? resolveMemoryBackend(settings).type === "qmd"
          ? await searchAgentMemoryWithQmd(rootDir, options.agentMemory, params.query, limit)
          : await searchAgentMemoryFile(rootDir, options.agentMemory, params.query, limit)
        : [];
      const projectResults = await searchProjectMemory(rootDir, {
        query: params.query,
        limit,
      }, settings);
      const results = [...agentResults, ...projectResults]
        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
        .slice(0, limit);

      if (results.length === 0) {
        return {
          content: [{ type: "text" as const, text: "NONE" }],
          details: { results: [] },
        };
      }

      const text = results.map((result, index) => [
        `${index + 1}. ${result.path}:${result.lineStart}-${result.lineEnd} (score ${result.score}, ${result.backend})`,
        result.snippet,
      ].join("\n")).join("\n\n");
      return { content: [{ type: "text" as const, text }], details: { results } };
    },
  };
}

export function createMemoryGetTool(rootDir: string, settings?: MemoryToolSettings, options?: MemoryToolOptions): ToolDefinition {
  return {
    name: "fn_memory_get",
    label: "Get Memory",
    description:
      "Read a bounded line window from a memory file returned by fn_memory_search. " +
      "Allowed files include project memory under .fusion/memory/ and this agent's own .fusion/agent-memory/{agentId}/MEMORY.md file.",
    parameters: memoryGetParams,
    execute: async (_id: string, params: Static<typeof memoryGetParams>) => {
      const agentResult = options?.agentMemory
        ? await getAgentMemoryWindow(rootDir, options.agentMemory, params.path, params.startLine, params.lineCount)
        : null;
      if (agentResult) {
        return {
          content: [{
            type: "text" as const,
            text: `${agentResult.path}:${agentResult.startLine}-${agentResult.endLine} (${agentResult.totalLines} total lines, ${agentResult.backend})\n\n${agentResult.content}`,
          }],
          details: agentResult,
        };
      }
      const result = await getProjectMemory(rootDir, {
        path: params.path,
        startLine: params.startLine,
        lineCount: params.lineCount,
      }, settings);
      return {
        content: [{
          type: "text" as const,
          text: `${result.path}:${result.startLine}-${result.endLine} (${result.totalLines} total lines, ${result.backend})\n\n${result.content}`,
        }],
        details: result,
      };
    },
  };
}

export function createMemoryAppendTool(rootDir: string, settings?: MemoryToolSettings, options?: MemoryToolOptions): ToolDefinition {
  return {
    name: "fn_memory_append",
    label: "Append Memory",
    description:
      "Append concise Markdown to memory. Use scope=\"agent\" for private operating context and scope=\"project\" for workspace-wide durable knowledge. " +
      "Use layer=\"long-term\" for durable conventions/decisions/pitfalls and layer=\"daily\" for running observations/open loops.",
    parameters: memoryAppendParams,
    execute: async (_id: string, params: Static<typeof memoryAppendParams>) => {
      const content = params.content.trim();
      if (!content) {
        return { content: [{ type: "text" as const, text: "ERROR: memory content cannot be empty" }], details: {} };
      }
      const scope = params.scope ?? "project";

      if (scope === "agent") {
        if (!options?.agentMemory) {
          return { content: [{ type: "text" as const, text: "ERROR: agent memory is not available in this session" }], details: {} };
        }
        const agentMemory = options.agentMemory;
        await syncAgentMemoryFile(rootDir, agentMemory);
        const targetPath = params.layer === "long-term"
          ? agentMemoryFilePath(rootDir, agentMemory.agentId)
          : agentDailyFilePath(rootDir, agentMemory.agentId);
        await appendFile(targetPath, `\n${content}\n`, "utf-8");
        if (resolveMemoryBackend(settings).type === "qmd") {
          void refreshAgentMemoryQmdIndex(rootDir, agentMemory).catch((err) => {
            log.warn(
              `Agent memory QMD index refresh failed for ${agentMemory.agentId}: ${err instanceof Error ? err.message : String(err)}`,
            );
          });
        }
        return {
          content: [{ type: "text" as const, text: `Appended to agent ${params.layer} memory.` }],
          details: { scope, layer: params.layer },
        };
      }

      await ensureOpenClawMemoryFiles(rootDir);
      const targetPath = params.layer === "long-term" ? memoryLongTermPath(rootDir) : dailyMemoryPath(rootDir);
      await appendFile(targetPath, `\n${content}\n`, "utf-8");
      if (resolveMemoryBackend(settings).type === "qmd") {
        scheduleQmdProjectMemoryRefresh(rootDir);
      }
      return {
        content: [{ type: "text" as const, text: `Appended to ${params.layer} memory.` }],
        details: { scope, layer: params.layer },
      };
    },
  };
}

export function createWebFetchTool(options?: { allowPrivateHosts?: boolean }): ToolDefinition {
  return {
    name: "fn_web_fetch",
    label: "WebFetch",
    description: "Fetch and extract readable text from a URL (lightweight HTTP fetch, no JS rendering).",
    parameters: webFetchParams,
    execute: async (_id: string, params: Static<typeof webFetchParams>) => {
      try {
        const result = await fetchWebContent(params.url, {
          timeoutMs: params.timeoutMs,
          maxBytes: params.maxBytes,
          allowPrivateHosts: options?.allowPrivateHosts ?? false,
        });
        const sections = [
          `URL: ${result.finalUrl}`,
          `Status: ${result.status}`,
          `Content-Type: ${result.contentType}`,
          params.prompt ? `Prompt: ${params.prompt}` : undefined,
          result.title ? `Title: ${result.title}` : undefined,
          "",
          result.content,
          result.truncated ? "\n[truncated to maxBytes]" : "",
        ].filter(Boolean);
        return {
          content: [{ type: "text" as const, text: sections.join("\n") }],
          details: {
            finalUrl: result.finalUrl,
            status: result.status,
            contentType: result.contentType,
            title: result.title,
            truncated: result.truncated,
            bytesRead: result.bytesRead,
            prompt: params.prompt,
          },
        };
      } catch (error) {
        if (error instanceof WebFetchError) {
          return {
            content: [{ type: "text" as const, text: `ERROR [${error.code}]: ${error.message}` }],
            details: { code: error.code, message: error.message },
            isError: true,
          };
        }
        const message = error instanceof Error ? error.message : String(error);
        return {
          content: [{ type: "text" as const, text: `ERROR [network-error]: ${message}` }],
          details: { code: "network-error", message },
          isError: true,
        };
      }
    },
  };
}

export function createMemoryTools(rootDir: string, settings?: MemoryToolSettings, options?: MemoryToolOptions): ToolDefinition[] {
  if (settings?.memoryEnabled === false) {
    return [];
  }
  const tools = [
    createMemorySearchTool(rootDir, settings, options),
    createMemoryGetTool(rootDir, settings, options),
  ];
  if (getMemoryBackendCapabilities(settings).writable) {
    tools.push(createMemoryAppendTool(rootDir, settings, options));
  }
  return tools;
}

/**
 * Create a `fn_reflect_on_performance` tool that asks the reflection service to
 * analyze recent agent performance and return actionable insights.
 */
export function createReflectOnPerformanceTool(
  reflectionService: AgentReflectionService,
  agentId: string,
): ToolDefinition {
  return {
    name: "fn_reflect_on_performance",
    label: "Reflect on Performance",
    description:
      'Review your past task performance and generate insights for improvement. Optionally focus on a specific area like "code quality", "speed", or "testing".',
    parameters: reflectOnPerformanceParams,
    execute: async (_id: string, params: Static<typeof reflectOnPerformanceParams>) => {
      const triggerDetail = params.focus_area
        ? `Agent-initiated reflection focused on: ${params.focus_area}`
        : "Agent-initiated reflection";

      const reflection = await reflectionService.generateReflection(agentId, "manual", {
        triggerDetail,
      });

      if (!reflection) {
        return {
          content: [{ type: "text" as const, text: "No reflection data available — not enough history yet." }],
          details: {},
        };
      }

      const formattedText = [
        `Summary: ${reflection.summary}`,
        "",
        "Insights:",
        ...reflection.insights.map((insight, index) => `${index + 1}. ${insight}`),
        "",
        "Suggested Improvements:",
        ...reflection.suggestedImprovements.map((improvement, index) => `${index + 1}. ${improvement}`),
      ].join("\n");

      return {
        content: [{ type: "text" as const, text: formattedText }],
        details: {},
      };
    },
  };
}

/**
 * Create a `fn_list_agents` tool that lists all available agents.
 *
 * @param agentStore - AgentStore for agent discovery
 * @returns ToolDefinition for the `fn_list_agents` tool
 */
function formatScore(score: number | null | undefined): string {
  if (typeof score !== "number" || !Number.isFinite(score)) return "n/a";
  return score.toFixed(2);
}

function buildPreview(value: string, limit = 100): string {
  const trimmed = value.trim();
  return trimmed.length > limit ? `${trimmed.slice(0, limit)}…` : trimmed;
}

export function createReadEvaluationsTool(
  agentStore: AgentStore,
  reflectionStore: ReflectionStore | undefined,
  agentId: string,
): ToolDefinition {
  return {
    name: "fn_read_evaluations",
    label: "Read Evaluations",
    description: "Read your ratings, recent feedback, and reflection history to support self-improvement.",
    parameters: readEvaluationsParams,
    execute: async (_id: string, _params: Static<typeof readEvaluationsParams>) => {
      const [summary, ratings] = await Promise.all([
        agentStore.getRatingSummary(agentId),
        agentStore.getRatings(agentId, { limit: 10 }),
      ]);

      const latestReflection = reflectionStore
        ? await reflectionStore.getLatestReflection(agentId)
        : null;
      const reflections = reflectionStore
        ? await reflectionStore.getReflections(agentId, 5)
        : [];

      const hasRatings = ratings.length > 0 || summary.totalRatings > 0;
      const hasReflections = Boolean(latestReflection) || reflections.length > 0;

      if (!hasRatings && !hasReflections) {
        return {
          content: [{ type: "text" as const, text: "No evaluation data available yet." }],
          details: {},
        };
      }

      const lines: string[] = [
        "Evaluation Summary",
        `- Average score: ${formatScore(summary.averageScore)}`,
        `- Trend: ${summary.trend}`,
        `- Total ratings: ${summary.totalRatings}`,
      ];

      const categoryEntries = Object.entries(summary.categoryAverages ?? {});
      if (categoryEntries.length > 0) {
        lines.push("", "Category averages:");
        for (const [category, score] of categoryEntries) {
          lines.push(`- ${category}: ${formatScore(score)}`);
        }
      }

      const commentedRatings = ratings.filter((rating) => rating.comment?.trim());
      if (commentedRatings.length > 0) {
        lines.push("", "Recent rating comments:");
        for (const rating of commentedRatings.slice(0, 5)) {
          lines.push(`- [${rating.score}/5] ${rating.comment!.trim()}`);
        }
      }

      if (latestReflection) {
        lines.push("", "Latest reflection:", `- Summary: ${latestReflection.summary}`);
        if (latestReflection.insights.length > 0) {
          lines.push("- Insights:");
          latestReflection.insights.forEach((insight) => lines.push(`  - ${insight}`));
        }
        if (latestReflection.suggestedImprovements.length > 0) {
          lines.push("- Suggested improvements:");
          latestReflection.suggestedImprovements.forEach((item) => lines.push(`  - ${item}`));
        }
      }

      if (reflections.length > 0) {
        lines.push("", "Recent reflection history:");
        for (const reflection of reflections.slice(0, 5)) {
          lines.push(`- ${reflection.timestamp}: ${reflection.summary}`);
        }
      }

      return {
        content: [{ type: "text" as const, text: lines.join("\n") }],
        details: {},
      };
    },
  };
}

export function createUpdateIdentityTool(agentStore: AgentStore, agentId: string): ToolDefinition {
  return {
    name: "fn_update_identity",
    label: "Update Identity",
    description: "Update your own soul, instructionsText, or memory fields based on evaluation feedback.",
    parameters: updateIdentityParams,
    execute: async (_id: string, params: Static<typeof updateIdentityParams>) => {
      const updates: AgentUpdateInput = {};

      if (params.soul !== undefined) {
        const soul = params.soul.trim();
        if (soul.length > MAX_SOUL_LENGTH) {
          return {
            content: [{ type: "text" as const, text: `ERROR: soul exceeds ${MAX_SOUL_LENGTH} character limit` }],
            details: {},
          };
        }
        updates.soul = soul;
      }

      if (params.instructionsText !== undefined) {
        const instructionsText = params.instructionsText.trim();
        if (instructionsText.length > MAX_INSTRUCTIONS_TEXT_LENGTH) {
          return {
            content: [{ type: "text" as const, text: `ERROR: instructionsText exceeds ${MAX_INSTRUCTIONS_TEXT_LENGTH} character limit` }],
            details: {},
          };
        }
        updates.instructionsText = instructionsText;
      }

      if (params.memory !== undefined) {
        const memory = params.memory.trim();
        if (memory.length > MAX_MEMORY_LENGTH) {
          return {
            content: [{ type: "text" as const, text: `ERROR: memory exceeds ${MAX_MEMORY_LENGTH} character limit` }],
            details: {},
          };
        }
        updates.memory = memory;
      }

      if (Object.keys(updates).length === 0) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Provide at least one field to update" }],
          details: {},
        };
      }

      await agentStore.updateAgent(agentId, updates);

      const confirmations = Object.entries(updates).map(([key, value]) => `- ${key}: ${buildPreview(String(value))}`);
      return {
        content: [{
          type: "text" as const,
          text: `Updated identity fields:\n${confirmations.join("\n")}`,
        }],
        details: { updatedFields: Object.keys(updates) },
      };
    },
  };
}

export function createListAgentsTool(agentStore: AgentStore): ToolDefinition {
  return {
    name: "fn_list_agents",
    label: "List Agents",
    description:
      "List all available agents in the system. Shows each agent's name, role, state, " +
      "personality (soul), and current assignment. Use this to discover which agents exist " +
      "and what they specialize in before delegating work.",
    parameters: listAgentsParams,
    execute: async (_id: string, params: Static<typeof listAgentsParams>) => {
      const filter: { role?: AgentCapability; state?: AgentState; includeEphemeral?: boolean } = {};
      if (params.role) filter.role = params.role as AgentCapability;
      if (params.state) filter.state = params.state as AgentState;
      if (params.includeEphemeral !== undefined) filter.includeEphemeral = params.includeEphemeral;

      const agents = await agentStore.listAgents(filter);

      if (agents.length === 0) {
        return {
          content: [{ type: "text" as const, text: "No agents found matching the specified filters." }],
          details: {},
        };
      }

      const lines = agents.map((agent) => {
        const parts: string[] = [
          `ID: ${agent.id}`,
          `Name: ${agent.name}`,
          `Role: ${agent.role}`,
          `State: ${agent.state}`,
        ];

        if (agent.title) parts.push(`Title: ${agent.title}`);
        if (agent.soul) parts.push(`Soul: ${agent.soul.slice(0, 200)}`);
        if (agent.instructionsText) {
          const snippet = agent.instructionsText.slice(0, 100);
          parts.push(`Custom Instructions: ${snippet}${agent.instructionsText.length > 100 ? "…" : ""}`);
        }
        if (agent.taskId) parts.push(`Current Task: ${agent.taskId}`);

        return parts.join("\n");
      });

      return {
        content: [{ type: "text" as const, text: `Available agents:\n\n${lines.join("\n\n")}` }],
        details: { agents },
      };
    },
  };
}

/**
 * Create a `fn_delegate_task` tool that creates and assigns a task to a specific agent.
 *
 * @param agentStore - AgentStore for agent lookup
 * @param taskStore - TaskStore for task creation
 * @returns ToolDefinition for the `fn_delegate_task` tool
 */
export function createGetAgentConfigTool(agentStore: AgentStore, callingAgentId: string): ToolDefinition {
  return {
    name: "fn_get_agent_config",
    label: "Get Agent Config",
    description: "Read full configuration for one of your direct-report agents.",
    parameters: getAgentConfigParams,
    execute: async (_id: string, params: Static<typeof getAgentConfigParams>) => {
      const target = await agentStore.getAgent(params.agent_id);
      if (!target) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Agent ${params.agent_id} not found` }],
          details: {},
        };
      }

      if (target.reportsTo !== callingAgentId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: You can only read configuration of agents that report to you" }],
          details: {},
        };
      }

      const runtimeConfig = (target.runtimeConfig ?? {}) as Record<string, unknown>;
      const lines: string[] = [
        `Agent Config: ${target.name} (${target.id})`,
        `Role: ${target.role}`,
        `State: ${target.state}`,
        `Title: ${target.title ?? "(none)"}`,
        `Icon: ${target.icon ?? "(none)"}`,
        "",
        "Soul:",
        target.soul ?? "(none)",
        "",
        "Instructions Text:",
        target.instructionsText ?? "(none)",
        `Instructions Path: ${target.instructionsPath ?? "(none)"}`,
        `Heartbeat Procedure Path: ${target.heartbeatProcedurePath ?? "(none)"}`,
        "",
        "Runtime Config:",
        `heartbeatIntervalMs: ${String(runtimeConfig.heartbeatIntervalMs ?? "(default)")}`,
        `heartbeatTimeoutMs: ${String(runtimeConfig.heartbeatTimeoutMs ?? "(default)")}`,
        `maxConcurrentRuns: ${String(runtimeConfig.maxConcurrentRuns ?? "(default)")}`,
        `messageResponseMode: ${String(runtimeConfig.messageResponseMode ?? "(default)")}`,
        `budget: ${JSON.stringify(runtimeConfig.budget ?? null)}`,
        "",
        "Memory:",
        target.memory ?? "(none)",
      ];

      return {
        content: [{ type: "text" as const, text: lines.join("\n") }],
        details: { agent: target },
      };
    },
  };
}

function isCallerPrivileged(caller: { id: string; role: string; reportsTo?: string | null } | null): boolean {
  if (!caller) return false;
  return caller.role === "ceo" || caller.reportsTo == null;
}

export function createUpdateAgentConfigTool(agentStore: AgentStore, callingAgentId: string): ToolDefinition {
  return {
    name: "fn_update_agent_config",
    label: "Update Agent Config",
    description: "Update configuration for one of your direct-report agents.",
    parameters: updateAgentConfigParams,
    execute: async (_id: string, params: Static<typeof updateAgentConfigParams>) => {
      const target = await agentStore.getAgent(params.agent_id);
      if (!target) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Agent ${params.agent_id} not found` }],
          details: {},
        };
      }

      if (target.reportsTo !== callingAgentId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: You can only update configuration of agents that report to you" }],
          details: {},
        };
      }

      if (isEphemeralAgent(target)) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Cannot update ephemeral/runtime agent ${params.agent_id}` }],
          details: {},
        };
      }

      if (params.soul && params.soul.length > 10000) {
        return {
          content: [{ type: "text" as const, text: "ERROR: soul exceeds 10000 character limit" }],
          details: {},
        };
      }
      if (params.instructions_text && params.instructions_text.length > 50000) {
        return {
          content: [{ type: "text" as const, text: "ERROR: instructions_text exceeds 50000 character limit" }],
          details: {},
        };
      }
      if (params.instructions_path && params.instructions_path.length > 500) {
        return {
          content: [{ type: "text" as const, text: "ERROR: instructions_path exceeds 500 character limit" }],
          details: {},
        };
      }
      if (params.heartbeat_procedure_path && params.heartbeat_procedure_path.length > 500) {
        return {
          content: [{ type: "text" as const, text: "ERROR: heartbeat_procedure_path exceeds 500 character limit" }],
          details: {},
        };
      }

      const hasRuntimeConfigUpdates = [
        params.heartbeat_interval_ms,
        params.heartbeat_timeout_ms,
        params.max_concurrent_runs,
        params.message_response_mode,
      ].some((value) => value !== undefined);

      const updateInput: AgentUpdateInput = {};
      if (params.soul !== undefined) updateInput.soul = params.soul;
      if (params.instructions_text !== undefined) updateInput.instructionsText = params.instructions_text;
      if (params.instructions_path !== undefined) updateInput.instructionsPath = params.instructions_path;
      if (params.heartbeat_procedure_path !== undefined) updateInput.heartbeatProcedurePath = params.heartbeat_procedure_path;
      if (hasRuntimeConfigUpdates) {
        updateInput.runtimeConfig = {
          ...((target.runtimeConfig ?? {}) as Record<string, unknown>),
          ...(params.heartbeat_interval_ms !== undefined ? { heartbeatIntervalMs: params.heartbeat_interval_ms } : {}),
          ...(params.heartbeat_timeout_ms !== undefined ? { heartbeatTimeoutMs: params.heartbeat_timeout_ms } : {}),
          ...(params.max_concurrent_runs !== undefined ? { maxConcurrentRuns: params.max_concurrent_runs } : {}),
          ...(params.message_response_mode !== undefined ? { messageResponseMode: params.message_response_mode } : {}),
        };
      }

      if (Object.keys(updateInput).length === 0) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Provide at least one field to update" }],
          details: {},
        };
      }

      const updated = await agentStore.updateAgent(params.agent_id, updateInput);
      const updatedRuntimeConfig = (updated.runtimeConfig ?? {}) as Record<string, unknown>;
      return {
        content: [{
          type: "text" as const,
          text: `Updated ${updated.name} (${updated.id})\n` +
            `heartbeatIntervalMs: ${String(updatedRuntimeConfig.heartbeatIntervalMs ?? "(default)")}\n` +
            `heartbeatTimeoutMs: ${String(updatedRuntimeConfig.heartbeatTimeoutMs ?? "(default)")}\n` +
            `maxConcurrentRuns: ${String(updatedRuntimeConfig.maxConcurrentRuns ?? "(default)")}\n` +
            `messageResponseMode: ${String(updatedRuntimeConfig.messageResponseMode ?? "(default)")}`,
        }],
        details: { agent: updated },
      };
    },
  };
}

/**
 * Create a `fn_delegate_task` tool that creates and assigns a task to a specific agent.
 *
 * @param agentStore - AgentStore for agent lookup
 * @param taskStore - TaskStore for task creation
 * @returns ToolDefinition for the `fn_delegate_task` tool
 */
type AgentProvisioningToolOptions = {
  hireApprovalEnabled?: boolean;
  approvalRequestStore?: ApprovalRequestStore;
  settingsProvider?: () => Promise<ProjectSettings | undefined>;
  runAuditor?: RunAuditor;
};

export function createAgentCreateTool(
  agentStore: AgentStore,
  callingAgentId: string,
  options?: AgentProvisioningToolOptions,
): ToolDefinition {
  return {
    name: "fn_agent_create",
    label: "Create Agent",
    description: "Create a new non-ephemeral direct-report agent.",
    parameters: createAgentParams,
    execute: async (_id: string, params: Static<typeof createAgentParams>) => {
      const caller = await agentStore.getAgent(callingAgentId);
      const privileged = isCallerPrivileged(caller);
      const reportsTo = params.reportsTo ?? callingAgentId;

      if (!privileged && reportsTo !== callingAgentId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: You can only create agents that report to you" }],
          details: {},
        };
      }

      const settings = await options?.settingsProvider?.();
      const fallbackSettings = !options?.settingsProvider && !options?.approvalRequestStore
        ? { agentProvisioning: { approvalMode: "never" as const } }
        : settings;
      const policy = resolveAgentProvisioningPolicy({
        tool: "fn_agent_create",
        caller: caller ? { id: caller.id, role: caller.role, isPrivileged: privileged } : undefined,
        settings: fallbackSettings,
      });
      await options?.runAuditor?.database({ type: "agent:create:requested", target: callingAgentId, metadata: { policy } });

      if (policy.decision === "require-approval") {
        if (!options?.approvalRequestStore) {
          await options?.runAuditor?.database({ type: "agent:create:denied", target: callingAgentId, metadata: { policy, reason: "approval-store-missing" } });
          return {
            content: [{ type: "text" as const, text: `DENIED: agent provisioning requires approval but approval storage is unavailable (${policy.matchedRule})` }],
            details: { outcome: "denied", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode },
          };
        }

        const approvalDedupeKey = computeApprovalDedupeKey({
          agentId: callingAgentId,
          toolName: "fn_agent_create",
          category: "agent_provisioning",
          resourceType: "agent",
          resourceId: reportsTo,
          operation: `create:${params.name}:${params.role}:${reportsTo}`,
        });

        const request = options.approvalRequestStore.create({
          requester: { actorId: callingAgentId, actorType: "agent", actorName: caller?.name ?? callingAgentId },
          targetAction: {
            category: "agent_provisioning",
            action: "create",
            summary: `Create agent ${params.name} (${params.role})`,
            resourceType: "agent",
            resourceId: "",
            context: { tool: "fn_agent_create", params, approvalDedupeKey },
          },
        });

        return {
          content: [{ type: "text" as const, text: `Approval required to create agent ${params.name}. Request ${request.id} created.` }],
          details: { outcome: "pending_approval", approvalRequestId: request.id, matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode },
        };
      }

      if (policy.decision === "deny") {
        await options?.runAuditor?.database({ type: "agent:create:denied", target: callingAgentId, metadata: { policy } });
        return {
          content: [{ type: "text" as const, text: `DENIED: agent provisioning blocked by policy (${policy.matchedRule})` }],
          details: { outcome: "denied", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode },
        };
      }

      const runtimeConfig: Record<string, unknown> = {
        ...(params.heartbeat_interval_ms !== undefined ? { heartbeatIntervalMs: params.heartbeat_interval_ms } : {}),
        ...(params.heartbeat_timeout_ms !== undefined ? { heartbeatTimeoutMs: params.heartbeat_timeout_ms } : {}),
        ...(params.max_concurrent_runs !== undefined ? { maxConcurrentRuns: params.max_concurrent_runs } : {}),
        ...(params.message_response_mode !== undefined ? { messageResponseMode: params.message_response_mode } : {}),
      };

      const created = await agentStore.createAgent({
        name: params.name,
        role: params.role,
        ...(params.soul !== undefined ? { soul: params.soul } : {}),
        ...(params.instructions_text !== undefined ? { instructionsText: params.instructions_text } : {}),
        ...(params.instructions_path !== undefined ? { instructionsPath: params.instructions_path } : {}),
        reportsTo,
        ...(Object.keys(runtimeConfig).length > 0 ? { runtimeConfig } : {}),
      });

      if (options?.hireApprovalEnabled) {
        await agentStore.updateAgentState(created.id, "paused");
        await agentStore.updateAgent(created.id, {
          metadata: { ...(created.metadata ?? {}), pendingApproval: true },
        });
      }

      await options?.runAuditor?.database({ type: "agent:create:approved", target: created.id, metadata: { policy, autoApproved: true } });
      return {
        content: [{ type: "text" as const, text: `Created agent ${created.name} (${created.id})${options?.hireApprovalEnabled ? " in pending_approval" : ""}` }],
        details: { outcome: "created", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode, agent: created, agentId: created.id, pendingApproval: options?.hireApprovalEnabled === true },
      };
    },
  };
}

export function createAgentDeleteTool(
  agentStore: AgentStore,
  callingAgentId: string,
  options?: AgentProvisioningToolOptions,
): ToolDefinition {
  return {
    name: "fn_agent_delete",
    label: "Delete Agent",
    description: "Delete one of your direct-report non-ephemeral agents.",
    parameters: deleteAgentParams,
    execute: async (_id: string, params: Static<typeof deleteAgentParams>) => {
      const caller = await agentStore.getAgent(callingAgentId);
      const target = await agentStore.getAgent(params.agent_id);
      if (!target) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Agent ${params.agent_id} not found` }],
          details: { outcome: "denied", matchedRule: "missing-target", effectiveMode: "trusted-only", agentId: params.agent_id },
        };
      }

      const privileged = isCallerPrivileged(caller);
      if (!privileged && target.reportsTo !== callingAgentId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: You can only delete agents that report to you" }],
          details: {},
        };
      }

      if (isEphemeralAgent(target)) {
        return { content: [{ type: "text" as const, text: `ERROR: Cannot delete ephemeral/runtime agent ${params.agent_id}` }], details: {} };
      }

      const settings = await options?.settingsProvider?.();
      const fallbackSettings = !options?.settingsProvider && !options?.approvalRequestStore
        ? { agentProvisioning: { approvalMode: "never" as const } }
        : settings;
      const policy = resolveAgentProvisioningPolicy({
        tool: "fn_agent_delete",
        caller: caller ? { id: caller.id, role: caller.role, isPrivileged: privileged } : undefined,
        settings: fallbackSettings,
      });
      await options?.runAuditor?.database({ type: "agent:delete:requested", target: target.id, metadata: { policy } });

      if (policy.decision === "require-approval") {
        if (!options?.approvalRequestStore) {
          await options?.runAuditor?.database({ type: "agent:delete:denied", target: target.id, metadata: { policy, reason: "approval-store-missing" } });
          return {
            content: [{ type: "text" as const, text: `DENIED: agent delete requires approval but approval storage is unavailable (${policy.matchedRule})` }],
            details: { outcome: "denied", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode, agentId: target.id },
          };
        }

        const approvalDedupeKey = computeApprovalDedupeKey({
          agentId: callingAgentId,
          toolName: "fn_agent_delete",
          category: "agent_provisioning",
          resourceType: "agent",
          resourceId: target.id,
          operation: `delete:${target.id}:${params.force === true ? "force" : "normal"}:${params.reassign_to ?? ""}`,
        });

        const request = options.approvalRequestStore.create({
          requester: { actorId: callingAgentId, actorType: "agent", actorName: caller?.name ?? callingAgentId },
          targetAction: {
            category: "agent_provisioning",
            action: "delete",
            summary: `Delete agent ${target.name} (${target.id})`,
            resourceType: "agent",
            resourceId: target.id,
            context: { tool: "fn_agent_delete", params, approvalDedupeKey },
          },
        });

        return {
          content: [{ type: "text" as const, text: `Approval required to delete agent ${target.name}. Request ${request.id} created.` }],
          details: { outcome: "pending_approval", approvalRequestId: request.id, matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode, agentId: target.id },
        };
      }

      if (policy.decision === "deny") {
        await options?.runAuditor?.database({ type: "agent:delete:denied", target: target.id, metadata: { policy } });
        return {
          content: [{ type: "text" as const, text: `DENIED: agent delete blocked by policy (${policy.matchedRule})` }],
          details: { outcome: "denied", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode, agentId: target.id },
        };
      }

      try {
        await agentStore.deleteAgent(params.agent_id, { force: params.force === true, reassignTo: params.reassign_to });
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error);
        return { content: [{ type: "text" as const, text: `ERROR: ${message}` }], details: {} };
      }

      await options?.runAuditor?.database({ type: "agent:delete:approved", target: target.id, metadata: { policy, autoApproved: true } });
      return {
        content: [{ type: "text" as const, text: `Deleted agent ${target.name} (${target.id})` }],
        details: { outcome: "deleted", matchedRule: policy.matchedRule, effectiveMode: policy.effectiveMode, agentId: target.id },
      };
    },
  };
}

export async function executeApprovedAgentProvisioning(
  approvalRequest: { id: string; status: string; targetAction: { resourceId: string } } & Parameters<typeof extractAgentProvisioningRequest>[0],
  deps: { agentStore: AgentStore },
): Promise<{ deletedId: string } | Awaited<ReturnType<AgentStore["createAgent"]>>> {
  if (approvalRequest.status !== "approved") {
    throw new Error(`Approval request ${approvalRequest.id} must be approved before provisioning execution`);
  }

  const { tool, params } = extractAgentProvisioningRequest(approvalRequest);
  if (tool === "fn_agent_create") {
    const runtimeConfig: Record<string, unknown> = {
      ...(typeof params.heartbeat_interval_ms === "number" ? { heartbeatIntervalMs: params.heartbeat_interval_ms } : {}),
      ...(typeof params.heartbeat_timeout_ms === "number" ? { heartbeatTimeoutMs: params.heartbeat_timeout_ms } : {}),
      ...(typeof params.max_concurrent_runs === "number" ? { maxConcurrentRuns: params.max_concurrent_runs } : {}),
      ...(typeof params.message_response_mode === "string" ? { messageResponseMode: params.message_response_mode } : {}),
    };

    return deps.agentStore.createAgent({
      name: String(params.name),
      role: String(params.role) as never,
      ...(typeof params.soul === "string" ? { soul: params.soul } : {}),
      ...(typeof params.instructions_text === "string" ? { instructionsText: params.instructions_text } : {}),
      ...(typeof params.instructions_path === "string" ? { instructionsPath: params.instructions_path } : {}),
      reportsTo: typeof params.reportsTo === "string" ? params.reportsTo : undefined,
      ...(Object.keys(runtimeConfig).length > 0 ? { runtimeConfig } : {}),
    });
  }

  await deps.agentStore.deleteAgent(approvalRequest.targetAction.resourceId, {
    force: params.force === true,
    reassignTo: typeof params.reassign_to === "string" ? params.reassign_to : undefined,
  });
  return { deletedId: approvalRequest.targetAction.resourceId };
}

export function createDelegateTaskTool(
  agentStore: AgentStore,
  taskStore: TaskStore,
  options?: AgentTaskCreationOptions,
): ToolDefinition {
  return {
    name: "fn_delegate_task",
    label: "Delegate Task",
    description:
      "Create a new task and assign it to a specific agent for execution. The task goes to " +
      "'todo' and will be picked up by the target agent on their next heartbeat cycle. " +
      "Use fn_list_agents first to find available agents and their capabilities.",
    parameters: delegateTaskParams,
    execute: async (_id: string, params: Static<typeof delegateTaskParams>) => {
      // Validate target agent exists
      const agent = await agentStore.getAgent(params.agent_id);
      if (!agent) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Agent ${params.agent_id} not found` }],
          details: {},
        };
      }

      // Validate target agent is not ephemeral
      if (isEphemeralAgent(agent)) {
        return {
          content: [{ type: "text" as const, text: `ERROR: Cannot delegate to ephemeral/runtime agent ${params.agent_id}` }],
          details: {},
        };
      }

      const override = params.override === true;
      const newTaskRef = { id: "<new>", column: "todo" } as const;
      if (!override && !canAgentTakeImplementationTaskForExplicitRouting(agent, { column: newTaskRef.column })) {
        return {
          content: [{ type: "text" as const, text: `ERROR: ${formatRoleMismatchReason(agent, newTaskRef)}` }],
          details: {},
        };
      }

      try {
        // Create task assigned to the target agent
        const { task, wasDuplicate } = await createAgentTask(taskStore, {
          description: params.description,
          dependencies: params.dependencies,
          column: "todo",
          assignedAgentId: params.agent_id,
          source: {
            sourceType: "api",
            ...(override ? { sourceMetadata: { executorRoleOverride: true } } : {}),
          },
        }, options);

        const deps = task.dependencies.length ? ` (depends on: ${task.dependencies.join(", ")})` : "";
        return {
          content: [{
            type: "text" as const,
            text: `Delegated to ${agent.name} (${agent.id}): ${wasDuplicate ? "Linked existing" : "Created"} ${task.id}${deps}. ` +
              `The task will be picked up by ${agent.name} on their next heartbeat cycle.`,
          }],
          details: { taskId: task.id, agentId: agent.id, agentName: agent.name },
        };
      } catch (err) {
        if (err instanceof Error && err.message.startsWith("Task ID already exists:")) {
          return {
            content: [{ type: "text" as const, text: `ERROR: ${err.message}` }],
            details: {},
            isError: true,
          };
        }
        throw err;
      }
    },
  };
}

/**
 * Create a `fn_send_message` tool that sends a message to another agent or user.
 *
 * @param messageStore - MessageStore for message persistence
 * @param fromAgentId - The agent ID sending the message
 * @returns ToolDefinition for the `fn_send_message` tool
 */
export function createSendMessageTool(
  messageStore: MessageStore,
  fromAgentId: string,
  options?: { autoRecovery?: ProjectSettings["autoRecovery"]; runAudit?: RunAuditor; taskStore?: TaskStore; settings?: Settings },
): ToolDefinition {
  const deliveryHandler = new MessageDeliveryAutoRecoveryHandler({
    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {}, sandbox: async () => {} },
  });

  return {
    name: "fn_send_message",
    label: "Send Message",
    description:
      "Send a message to another agent or user. The recipient will be woken if they have " +
      "`messageResponseMode: 'immediate'` configured. When replying to an existing message, " +
      "include `reply_to_message_id` to preserve threading.",
    parameters: sendMessageParams,
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    execute: async (_id: string, params: Static<typeof sendMessageParams>, _signal?: any, _onUpdate?: any, _ctx?: any) => {
      const content = params.content.trim();
      if (content.length === 0) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Message content cannot be empty" }],
          details: {},
        };
      }
      if (content.length > 2000) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Message content exceeds 2000 character limit" }],
          details: {},
        };
      }

      try {
        const inferredDashboardRecipient = normalizeMessageParticipant(params.to_id, "user");
        const messageType = params.type
          ?? (inferredDashboardRecipient.id === DASHBOARD_USER_ID ? "agent-to-user" : "agent-to-agent");
        const recipientType: "user" | "agent" = messageType === "agent-to-user" ? "user" : "agent";
        const recipient = recipientType === "user"
          ? normalizeMessageParticipant(params.to_id, recipientType)
          : { id: params.to_id, type: recipientType };
        const replyToMessageId = params.reply_to_message_id?.trim();

        if (params.reply_to_message_id !== undefined && !replyToMessageId) {
          return {
            content: [{ type: "text" as const, text: "ERROR: reply_to_message_id must be a non-empty string" }],
            details: {},
          };
        }

        const result = await deliveryHandler.runWithBoundedRetry({
          run: async () => Promise.resolve(messageStore.sendMessage({
            fromId: fromAgentId,
            fromType: "agent",
            toId: recipient.id,
            toType: recipient.type,
            content,
            type: messageType,
            ...(replyToMessageId ? { metadata: { replyTo: { messageId: replyToMessageId } } } : {}),
          })),
          correlation: { kind: "direct", fromAgentId, toId: recipient.id },
        }, options?.autoRecovery ?? { mode: "deterministic-only", maxRetries: 3 }, async () => {
          const taskId = _ctx?.taskId as string | undefined;
          if (!taskId || !options?.taskStore || !options.settings) {
            return;
          }
          const task = await options.taskStore.getTask(taskId);
          if (!task) {
            return;
          }
          await recordRetry({ store: options.taskStore, settings: options.settings, task, category: "messageDelivery", role: "executor", agentId: fromAgentId });
        });

        if (result.outcome === "parked") {
          return {
            content: [{ type: "text" as const, text: `ERROR: Failed to send message: ${result.error.message}` }],
            details: {},
          };
        }

        return {
          content: [{
            type: "text" as const,
            text: `Message sent to ${recipient.id === DASHBOARD_USER_ID ? DASHBOARD_USER_ID : params.to_id} (ID: ${result.value.id})`,
          }],
          details: { messageId: result.value.id },
        };
      } catch (err) {
        const errorMessage = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to send message: ${errorMessage}` }],
          details: {},
        };
      }
    },
  };
}

/**
 * Create a `fn_read_messages` tool that reads inbox messages for an agent.
 *
 * @param messageStore - MessageStore for message retrieval
 * @param agentId - The agent ID whose inbox to read
 * @returns ToolDefinition for the `fn_read_messages` tool
 */
type ResearchToolsOptions = {
  store: TaskStore;
  rootDir: string;
  getSettings: () => Promise<Settings>;
};

function formatResearchRunDetails(run: ResearchRun) {
  const findings = run.results?.findings ?? [];
  const citations = run.results?.citations ?? [];
  return {
    runId: run.id,
    status: run.status,
    query: run.query,
    summary: run.results?.summary ?? null,
    findings,
    citations,
    sourceCount: run.sources.length,
    error: run.error ?? null,
    setup: null as null | { code: string; message: string },
  };
}

function researchUnavailable(code: string, message: string) {
  return {
    content: [{ type: "text" as const, text: message }],
    details: {
      runId: null,
      status: "unavailable",
      summary: null,
      findings: [],
      citations: [],
      error: message,
      setup: { code, message },
    },
  };
}

export function createResearchTools(options: ResearchToolsOptions): ToolDefinition[] {
  const orchestratorState: {
    orchestrator: ResearchOrchestrator | null;
    providerRegistry: ResearchProviderRegistry | null;
    inFlight: Map<string, Promise<void>>;
  } = {
    orchestrator: null,
    providerRegistry: null,
    inFlight: new Map(),
  };

  const ensureOrchestrator = async (): Promise<ResearchOrchestrator | null> => {
    const settings = await options.getSettings();
    const resolved = resolveResearchSettings(settings);
    if (!resolved.enabled) {
      return null;
    }

    if (!orchestratorState.providerRegistry) {
      orchestratorState.providerRegistry = new ResearchProviderRegistry(settings, options.rootDir);
    } else {
      orchestratorState.providerRegistry.refreshSettings(settings);
    }

    const registry = orchestratorState.providerRegistry;
    const availableProviders = registry.getAvailableProviders();
    if (availableProviders.length === 0) {
      return null;
    }

    if (!orchestratorState.orchestrator) {
      const stepRunner = new ResearchStepRunner({
        providers: availableProviders
          .map((type) => registry.getProvider(type))
          .filter((provider): provider is NonNullable<typeof provider> => Boolean(provider)),
      });
      orchestratorState.orchestrator = new ResearchOrchestrator({
        store: options.store.getResearchStore(),
        stepRunner,
        maxConcurrentRuns: resolved.limits.maxConcurrentRuns,
      });
    }

    return orchestratorState.orchestrator;
  };

  const runTool: ToolDefinition = {
    name: "fn_research_run",
    label: "Run Research",
    description: "Start a bounded research run and optionally wait for completion to get findings.",
    parameters: researchRunParams,
    execute: async (_id: string, params: Static<typeof researchRunParams>) => {
      const settings = await options.getSettings();
      const resolved = resolveResearchSettings(settings);
      if (!resolved.enabled) {
        return researchUnavailable("feature-disabled", "Research is disabled in settings. Enable researchSettings.enabled or global research defaults first.");
      }
      const orchestrator = await ensureOrchestrator();
      if (!orchestrator) {
        return researchUnavailable("provider-unavailable", "Research providers are not configured. Add provider credentials in Settings → Authentication and select a research provider.");
      }

      const registry = orchestratorState.providerRegistry;
      const availableProviderTypes = registry?.getAvailableProviders() ?? [];
      const runId = orchestrator.createRun({
        providers: availableProviderTypes
          .filter((type) => type !== "llm-synthesis")
          .map((type) => ({ type, config: { maxResults: resolved.limits.maxSourcesPerRun, timeoutMs: resolved.limits.requestTimeoutMs } })),
        maxSources: resolved.limits.maxSourcesPerRun,
        maxSynthesisRounds: Math.max(1, settings.researchMaxSynthesisRounds ?? settings.researchGlobalMaxSynthesisRounds ?? 2),
        phaseTimeoutMs: resolved.limits.maxDurationMs,
        stepTimeoutMs: resolved.limits.requestTimeoutMs,
      });

      const runPromise = orchestrator.startRun(runId, params.query);
      orchestratorState.inFlight.set(runId, runPromise.then(() => undefined).catch(() => undefined));
      void runPromise.finally(() => orchestratorState.inFlight.delete(runId));

      if (!params.wait_for_completion) {
        const started = options.store.getResearchStore().getRun(runId);
        if (!started) {
          return {
            content: [{ type: "text" as const, text: `Started research run ${runId} for: ${params.query}` }],
            details: { runId, status: "pending", summary: null, findings: [], citations: [], sourceCount: 0, error: null, setup: null },
          };
        }
        return {
          content: [{ type: "text" as const, text: `Started research run ${runId} for: ${params.query}` }],
          details: formatResearchRunDetails(started),
        };
      }

      const maxWaitMs = Math.max(1_000, Math.min(params.max_wait_ms ?? 90_000, resolved.limits.maxDurationMs));
      const completed = await Promise.race([
        runPromise,
        new Promise<ResearchRun>((resolve) => setTimeout(() => {
          const latest = options.store.getResearchStore().getRun(runId);
          resolve(latest ?? ({
            id: runId,
            query: params.query,
            status: "running",
            sources: [],
            events: [],
            tags: [],
            createdAt: new Date().toISOString(),
            updatedAt: new Date().toISOString(),
          } as ResearchRun));
        }, maxWaitMs)),
      ]);
      const details = formatResearchRunDetails(completed);
      const text = details.status === "completed"
        ? `Research run ${runId} completed. ${details.summary ?? "No summary generated."}`
        : `Research run ${runId} is ${details.status}. Use fn_research_get for updates.`;
      return { content: [{ type: "text" as const, text }], details };
    },
  };

  const listTool: ToolDefinition = {
    name: "fn_research_list",
    label: "List Research Runs",
    description: "List recent research runs with status and summary snippets.",
    parameters: researchListParams,
    execute: async (_id: string, params: Static<typeof researchListParams>) => {
      const limit = Math.max(1, Math.min(params.limit ?? 10, 50));
      const runs = options.store.getResearchStore().listRuns({
        status: params.status as ResearchRunStatus | undefined,
        limit,
      });
      const text = runs.length
        ? runs.map((run) => `- ${run.id} [${run.status}] ${run.query}`).join("\n")
        : "No research runs found.";
      return {
        content: [{ type: "text" as const, text }],
        details: { runs: runs.map((run) => formatResearchRunDetails(run)) },
      };
    },
  };

  const getTool: ToolDefinition = {
    name: "fn_research_get",
    label: "Get Research Run",
    description: "Get one research run with structured findings and citations.",
    parameters: researchGetParams,
    execute: async (_id: string, params: Static<typeof researchGetParams>) => {
      const run = options.store.getResearchStore().getRun(params.id);
      if (!run) {
        return {
          content: [{ type: "text" as const, text: `Research run ${params.id} not found.` }],
          details: { runId: params.id, status: "missing", summary: null, findings: [], citations: [], error: "not found", setup: null },
        };
      }
      const details = formatResearchRunDetails(run);
      return {
        content: [{ type: "text" as const, text: `Research run ${run.id} is ${run.status}.` }],
        details,
      };
    },
  };

  const cancelTool: ToolDefinition = {
    name: "fn_research_cancel",
    label: "Cancel Research Run",
    description: "Cancel an active research run.",
    parameters: researchCancelParams,
    execute: async (_id: string, params: Static<typeof researchCancelParams>) => {
      const orchestrator = await ensureOrchestrator();
      if (!orchestrator) {
        return researchUnavailable("provider-unavailable", "Research orchestrator is unavailable because research providers are not configured.");
      }
      const cancelled = orchestrator.cancelRun(params.id);
      const run = options.store.getResearchStore().getRun(params.id);
      if (!run) {
        return {
          content: [{ type: "text" as const, text: `Research run ${params.id} not found.` }],
          details: { runId: params.id, status: "missing", summary: null, findings: [], citations: [], error: "not found", setup: null },
        };
      }
      return {
        content: [{ type: "text" as const, text: cancelled ? `Cancellation requested for ${params.id}.` : `Run ${params.id} is not active.` }],
        details: formatResearchRunDetails(run),
      };
    },
  };

  return [runTool, listTool, getTool, cancelTool];
}

export function createPostRoomMessageTool(
  chatStore: ChatStore,
  fromAgentId: string,
  options?: { autoRecovery?: ProjectSettings["autoRecovery"]; runAudit?: RunAuditor; taskStore?: TaskStore; settings?: Settings },
): ToolDefinition {
  const deliveryHandler = new MessageDeliveryAutoRecoveryHandler({
    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {}, sandbox: async () => {} },
  });

  return {
    name: "fn_post_room_message",
    label: "Post Room Message",
    description:
      "Post a message to a room you are a member of. Room membership is enforced before posting, " +
      "so only reply when the room content is relevant to your role or identity.",
    parameters: postRoomMessageParams,
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    execute: async (_id: string, params: Static<typeof postRoomMessageParams>, _signal?: any, _onUpdate?: any, _ctx?: any) => {
      const content = params.content.trim();
      if (content.length === 0) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Message content cannot be empty" }],
          details: {},
        };
      }
      if (content.length > 2000) {
        return {
          content: [{ type: "text" as const, text: "ERROR: Message content exceeds 2000 character limit" }],
          details: {},
        };
      }

      const replyToMessageId = params.replyToMessageId?.trim();
      if (params.replyToMessageId !== undefined && !replyToMessageId) {
        return {
          content: [{ type: "text" as const, text: "ERROR: replyToMessageId must be a non-empty string" }],
          details: {},
        };
      }

      try {
        const isMember = chatStore.listRoomMembers(params.roomId).some((member) => member.agentId === fromAgentId);
        if (!isMember) {
          return {
            content: [{ type: "text" as const, text: `ERROR: Agent ${fromAgentId} is not a member of room ${params.roomId}` }],
            details: {},
            isError: true,
          };
        }

        const result = await deliveryHandler.runWithBoundedRetry({
          run: async () => Promise.resolve(chatStore.addRoomMessage(params.roomId, {
            role: "assistant",
            senderAgentId: fromAgentId,
            content,
            mentions: params.mentions ?? [],
            ...(replyToMessageId ? { metadata: { replyToMessageId } } : {}),
          })),
          correlation: { kind: "room", fromAgentId, roomId: params.roomId },
        }, options?.autoRecovery ?? { mode: "deterministic-only", maxRetries: 3 }, async () => {
          const taskId = _ctx?.taskId as string | undefined;
          if (!taskId || !options?.taskStore || !options.settings) {
            return;
          }
          const task = await options.taskStore.getTask(taskId);
          if (!task) {
            return;
          }
          await recordRetry({ store: options.taskStore, settings: options.settings, task, category: "messageDelivery", role: "executor", agentId: fromAgentId });
        });

        if (result.outcome === "parked") {
          return {
            content: [{ type: "text" as const, text: `ERROR: Failed to post room message: ${result.error.message}` }],
            details: {},
            isError: true,
          };
        }

        return {
          content: [{ type: "text" as const, text: `Room message posted to ${params.roomId} (ID: ${result.value.id})` }],
          details: { messageId: result.value.id },
        };
      } catch (err) {
        const errorMessage = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to post room message: ${errorMessage}` }],
          details: {},
          isError: true,
        };
      }
    },
  };
}

export function createReadMessagesTool(messageStore: MessageStore, agentId: string): ToolDefinition {
  const REPLY_CONTEXT_CONTENT_MAX_CHARS = 400;

  const trimReplyContent = (value: string): string => {
    if (value.length <= REPLY_CONTEXT_CONTENT_MAX_CHARS) {
      return value;
    }
    return `${value.slice(0, REPLY_CONTEXT_CONTENT_MAX_CHARS - 1)}…`;
  };

  const resolveReplyContext = (msg: Message): {
    parentMessageId: string;
    parentMessage: Message | null;
    missingParent: boolean;
  } | null => {
    const metadata = msg.metadata;
    const parentMessageId = typeof metadata === "object"
      && metadata !== null
      && "replyTo" in metadata
      && typeof metadata.replyTo === "object"
      && metadata.replyTo !== null
      && "messageId" in metadata.replyTo
      && typeof metadata.replyTo.messageId === "string"
      ? metadata.replyTo.messageId
      : null;

    if (!parentMessageId) {
      return null;
    }

    const parentMessage = messageStore.getMessage(parentMessageId);
    return {
      parentMessageId,
      parentMessage,
      missingParent: !parentMessage,
    };
  };

  return {
    name: "fn_read_messages",
    label: "Read Messages",
    description: "Read your inbox messages. Returns unread messages by default.",
    parameters: readMessagesParams,
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    execute: async (_id: string, params: Static<typeof readMessagesParams>, _signal?: any, _onUpdate?: any, _ctx?: any) => {
      const unreadOnly = params.unread_only ?? true;
      const limit = params.limit ?? 20;

      try {
        const filter = {
          ...(unreadOnly ? { read: false as const } : {}),
          limit,
        };

        const messages = messageStore.getInbox(agentId, "agent", filter);

        if (messages.length === 0) {
          return {
            content: [{ type: "text" as const, text: "No messages" }],
            details: {},
          };
        }

        const messageEntries = messages.map((msg: Message) => {
          const replyContext = resolveReplyContext(msg);
          return {
            message: msg,
            replyContext,
          };
        });

        const lines = messageEntries.map(({ message, replyContext }) => {
          const timestamp = new Date(message.createdAt).toLocaleString();
          const readStatus = message.read ? "[read] " : "[unread] ";
          const baseLine = `${readStatus}[id: ${message.id}] [from: ${message.fromType}:${message.fromId}] ${message.content} (${timestamp})`;
          if (!replyContext) {
            return baseLine;
          }

          if (replyContext.parentMessage) {
            const parent = replyContext.parentMessage;
            return `${baseLine}\n  ↳ reply-to [id: ${parent.id}] [from: ${parent.fromType}:${parent.fromId}] ${trimReplyContent(parent.content)}`;
          }

          return `${baseLine}\n  ↳ reply-to [id: ${replyContext.parentMessageId}] (missing parent message)`;
        });

        return {
          content: [{
            type: "text" as const,
            text: `Messages (${messages.length}):\n${lines.join("\n")}`,
          }],
          details: {
            messages,
            threadContext: messageEntries
              .filter((entry) => entry.replyContext)
              .map((entry) => ({
                messageId: entry.message.id,
                replyTo: entry.replyContext,
              })),
          },
        };
      } catch (err) {
        const errorMessage = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `ERROR: Failed to read messages: ${errorMessage}` }],
          details: {},
        };
      }
    },
  };
}