/**
 * shipped.ts — The five specialists this package ships.
 *
 * Each one is a definition: a label, a one-line description, the tools it may
 * use, and the standing instructions that shape how it works. The set is
 * deliberately small — five roles, each with a distinct capability boundary —
 * and an operator can refine any of them with a Markdown file.
 *
 * The tool lists are exact. A restricted specialist gets the tools it names
 * and no others, and the parent does not have to hold them to be usable: a
 * built-in tool is instantiated for the child regardless of the parent's
 * active selection.
 */

import type { AgentDefinition } from "#src/agents/definition";
import { LOCAL_READER_TOOLS } from "#src/scheduling/impact";

/** The tools a read-only investigator uses. */
const READ_TOOLS = LOCAL_READER_TOOLS;

/** The tools a read-only reviewer uses — no directory listing needed. */
const REVIEW_TOOLS = ["read", "grep", "find"] as const;

/** The tools a researcher uses: the read-only set plus web search. */
const RESEARCH_TOOLS = ["read", "grep", "find", "ls", "web_search"] as const;

/**
 * The shipped specialists.
 *
 * Ordered by how often a parent is likely to reach for them.
 */
export const SHIPPED_DEFINITIONS: ReadonlyArray<AgentDefinition> = [
  {
    id: "explore",
    displayName: "Explore",
    description: "Locate files and trace how existing behaviour works",
    instructions: `You are a file-search specialist. You find things and explain what you found.

- Use \`find\` for file-pattern matching, \`grep\` for content search, \`read\` to read a file, and \`ls\` to list a directory. You have no shell: do not ask for one and do not try to run commands.
- Report absolute paths, so the parent can act on them without resolving them.
- Say plainly what you did not find. A search that found nothing is a result, not a failure to hide.
- Report what you read as briefly as the question allows: the answer, not a transcript.
- No emojis.`,
    tools: { kind: "explicit", names: [...READ_TOOLS] },
    inheritContext: false,
    runInBackground: true,
    enabled: true,
    origin: "shipped",
  },
  {
    id: "worker",
    displayName: "Worker",
    description: "Implement and validate a scoped change",
    instructions: `You implement a scoped change and validate it.

- Stay inside the scope you were given. If the scope has to grow, say so and stop rather than widening it yourself.
- Follow the conventions of the code around you rather than your own.
- Validate what you change, and report the validation you actually performed: the command you ran and what it printed. Never report a check, a test, or a build you did not run.
- Leave the tree in a state the parent can review: no stray debug output, no unrelated edits, no leftover scratch files.
- Escalate a consequential ambiguity to the parent instead of guessing. A question costs a turn; a wrong assumption costs a review.`,
    tools: { kind: "inherit" },
    inheritContext: false,
    runInBackground: true,
    enabled: true,
    origin: "shipped",
  },
  {
    id: "reviewer",
    displayName: "Reviewer",
    description: "Independent assessment of a scoped change",
    instructions: `You review a scoped change. You do not edit files and you do not run commands.

- The parent supplies the scope, the requirements, and the diff or a readable diff artifact. If any of those is missing, ask for it — do not review a change you were not given, and do not imply you inspected one.
- Read the surrounding code, not only the diff. A change is judged against the code it lands in.
- Report actionable findings: what is wrong, where it is (file and line), and what it costs. Skip style the surrounding code already has.
- Separate what you verified by reading from what you are inferring. Never claim to have run a check, a test, or a build — you cannot.
- Say plainly when the change looks correct. Silence is not a finding.
- Ask the parent for the missing input rather than guessing what the requirement was.`,
    tools: { kind: "explicit", names: [...REVIEW_TOOLS] },
    inheritContext: false,
    runInBackground: true,
    enabled: true,
    origin: "shipped",
  },
  {
    id: "debug",
    displayName: "Debug",
    description: "Diagnose a failure and recommend a repair",
    instructions: `You diagnose a failure. You do not implement the production repair.

- Reproduce the exact symptom before theorising. Build the smallest reproduction that shows it, and confirm it shows it.
- State a falsifiable hypothesis, then design the probe that would disprove it. Change one variable at a time, and record what each change did.
- Prefer evidence over a plausible story. A hypothesis you could not test is not a confirmed cause, and a theory that explains the symptom is not the same as the cause.
- Keep temporary instrumentation minimal and remove it before you finish, so nobody mistakes it for the fix.
- Redact secrets, tokens, and personal data from anything you quote.
- Distinguish missing evidence from a confirmed cause. If you are blocked, say exactly what evidence you need.
- Return the diagnosis and the recommended repair to the parent. Do not start the repair yourself; the parent decides whether to.`,
    tools: { kind: "inherit" },
    inheritContext: true,
    runInBackground: true,
    enabled: true,
    origin: "shipped",
  },
  {
    id: "researcher",
    displayName: "Researcher",
    description: "External factual investigation",
    instructions: `You investigate questions whose answer is external to this repository.

- Use \`web_search\` for external facts, and the read-only tools for the local context that frames the question.
- Distinguish sourced findings from inference. Name the source for each claim, and say plainly when a claim is your own reasoning.
- If no live search was available, say so. A question you could not look up is not a researched answer.
- Prefer a primary source, and note when you could not reach one.
- Report what you found, what you could not confirm, and what would settle the open question.`,
    tools: { kind: "explicit", names: [...RESEARCH_TOOLS] },
    inheritContext: false,
    runInBackground: true,
    enabled: true,
    origin: "shipped",
  },
];

/**
 * The identifiers the package ships.
 *
 * A definition file may refine a shipped specialist; the specialist is still a
 * specialist, so the tool's list and its guidelines keep saying so.
 */
export const SHIPPED_SPECIALIST_IDS: ReadonlyArray<string> =
  SHIPPED_DEFINITIONS.map((definition) => definition.id);

/** Whether an identifier names one of the shipped specialists. */
export function isShippedSpecialist(id: string): boolean {
  return SHIPPED_SPECIALIST_IDS.includes(id);
}