///|
/// A tool the model may call and the function behind it. The descriptor is what the model sees;
/// the function is handed the arguments object and the run it belongs to, and returns the text
/// the model reads back.
///
/// The run context is what makes a stateful tool possible — a todo list remembers itself, a
/// retrieval tool can see what the run already looked at — without a second tool interface.
pub(all) struct ToolSpec {
  tool : @moonmuse.Tool
  run : async (Json, RunContext) -> String
}

///|
/// A tool with a JSON-schema descriptor.
pub fn ToolSpec::new(
  name~ : String,
  description~ : String,
  run~ : async (Json, RunContext) -> String,
  schema? : Json,
) -> ToolSpec {
  { tool: @moonmuse.Tool::new(name, description, schema?), run, }
}

///|
/// What a tool hands back to the model, from any value its function returns: the JSON text of the
/// value. A `String` is passed through as it is by the code `#tool` generates, so a tool that
/// answers in prose is not quoted.
pub fn[T : ToJson] tool_result(value : T) -> String {
  @moonjson.dumps(value.to_json())
}

///|
/// A tool whose descriptor is already built.
pub fn ToolSpec::of(
  tool : @moonmuse.Tool,
  run : async (Json, RunContext) -> String,
) -> ToolSpec {
  { tool, run, }
}

///|
/// The tools being collected for an agent: what the config brings, and what each middleware
/// adds when the agent is built.
pub struct Tools {
  mut specs : Array[ToolSpec]
}

///|
/// An empty collection.
pub fn Tools::new() -> Tools {
  { specs: [], }
}

///|
/// Add one, replacing a tool of the same name so a later registration wins.
pub fn Tools::add(self : Tools, spec : ToolSpec) -> Unit {
  let kept = self.specs.filter(existing => existing.tool.name != spec.tool.name)
  self.specs = [..kept, spec]
}

///|
/// Add a tool by name, description and body.
pub fn Tools::register(
  self : Tools,
  name~ : String,
  description~ : String,
  run~ : async (Json, RunContext) -> String,
  schema? : Json,
) -> Unit {
  self.add(ToolSpec::new(name~, description~, run~, schema?))
}

///|
/// The collected tools.
pub fn Tools::specs(self : Tools) -> Array[ToolSpec] {
  self.specs
}

///|
/// Everything an agent is configured with, short of the provider and the checkpoint stores.
///
/// A config is data plus a strategy: copying it and changing one field is how a second agent is
/// made, and the presets are the three shapes a run usually takes.
pub(all) struct AgentConfig {
  name : String
  model : String
  instructions : String?
  tools : Array[ToolSpec]
  options : Options
  limits : Limits
  middleware : Array[&Middleware]
  strategy : Strategy?
  structured : Structured?
  events : EventHandler
  exit_tool : String?
  missing_tools : MissingTools
  nodes : Map[String, NodeFn]
}

///|
/// A config for `model` that runs the single-run loop.
pub fn AgentConfig::new(
  model : String,
  name~ : String = "agent",
) -> AgentConfig {
  {
    name,
    model,
    instructions: None,
    tools: [],
    options: default_options,
    limits: default_limits,
    middleware: [],
    strategy: None,
    structured: None,
    events: EventHandler::new(),
    exit_tool: None,
    missing_tools: Keep,
    nodes: Map([]),
  }
}

///|
/// The tool a chat strategy ends on: the model calls it when the conversation is over.
pub fn AgentConfig::exit_tool_spec() -> ToolSpec {
  ToolSpec::new(
    name="__exit__",
    description="End the conversation. Call this when there is nothing more to do.",
    schema=Json::object(Map([("type", Json::string("object"))])),
    run=fn(_args, _context) { "conversation finished" },
  )
}

///|
/// A config for the chat loop: the model must call tools, and calls `__exit__` to finish.
pub fn AgentConfig::chat(
  model : String,
  name~ : String = "agent",
) -> AgentConfig {
  let config = AgentConfig::new(model, name~)
  {
    ..config,
    strategy: Some(chat()),
    exit_tool: Some("__exit__"),
    tools: [AgentConfig::exit_tool_spec()],
  }
}

///|
/// A config for the reason-and-act loop.
pub fn AgentConfig::react(
  model : String,
  name~ : String = "agent",
  reasoning_prompt~ : String = "Think about what you have learned and what the next step should be.",
  interval~ : Int32 = 1,
) -> AgentConfig {
  {
    ..AgentConfig::new(model, name~),
    strategy: Some(react(reasoning_prompt~, interval~)),
  }
}

///|
/// A copy with the system instructions replaced.
pub fn AgentConfig::with_instructions(
  self : AgentConfig,
  instructions : String,
) -> AgentConfig {
  { ..self, instructions: Some(instructions), }
}

///|
/// A copy with tools added.
pub fn AgentConfig::with_tools(
  self : AgentConfig,
  tools : Array[ToolSpec],
) -> AgentConfig {
  let all = self.tools.copy()
  for spec in tools {
    all.push(spec)
  }
  { ..self, tools: all, }
}

///|
/// A copy with one more middleware, outermost last.
pub fn AgentConfig::with_middleware(
  self : AgentConfig,
  middleware : &Middleware,
) -> AgentConfig {
  let all = self.middleware.copy()
  all.push(middleware)
  { ..self, middleware: all, }
}

///|
/// A copy running the given strategy.
pub fn AgentConfig::with_strategy(
  self : AgentConfig,
  strategy : Strategy,
) -> AgentConfig {
  { ..self, strategy: Some(strategy), }
}

///|
/// A copy with the given caps.
pub fn AgentConfig::with_limits(
  self : AgentConfig,
  limits : Limits,
) -> AgentConfig {
  { ..self, limits, }
}

///|
/// A copy that rewrites the tool calls and results naming tools it does not have, so a
/// conversation recorded under a wider tool set can still be sent to a provider.
pub fn AgentConfig::with_missing_tools(
  self : AgentConfig,
  policy : MissingTools,
) -> AgentConfig {
  { ..self, missing_tools: policy, }
}

///|
/// A copy with the given request settings.
pub fn AgentConfig::with_options(
  self : AgentConfig,
  options : Options,
) -> AgentConfig {
  { ..self, options, }
}

///|
/// A copy asking for structured output against `schema`.
pub fn AgentConfig::with_structured(
  self : AgentConfig,
  structured : Structured,
) -> AgentConfig {
  { ..self, structured: Some(structured), }
}

///|
/// A copy reporting to the given handlers.
pub fn AgentConfig::with_events(
  self : AgentConfig,
  events : EventHandler,
) -> AgentConfig {
  { ..self, events, }
}

///|
/// A copy with a custom node body registered under `name`, for a strategy that names it. The
/// body is handed the agent's runtime, so a composed strategy reaches the model, the tools and
/// the middleware exactly as a built-in node does.
pub fn AgentConfig::with_node(
  self : AgentConfig,
  name : String,
  body : NodeFn,
) -> AgentConfig {
  let nodes = self.nodes.copy()
  nodes[name] = body
  { ..self, nodes, }
}

///|
/// A run that went wrong, or one that was interrupted and can be resumed.
///
/// `Engine` carries the graph engine's own error unchanged so that an interrupt, a step limit
/// and a backend failure stay distinguishable to the caller.
pub(all) suberror AgentError {
  Exhausted(limit~ : Int32)
  Refused(reason~ : String)
  Engine(@moonstate.GraphError)
}

///|
/// Turn the failure a node recorded back into the error a caller sees.
fn recorded_failure(state : AgentState) -> AgentError? {
  match state.storage.get(error_key) {
    Some(String(reason)) => Some(Refused(reason~))
    Some(json) =>
      match json {
        Object(fields) =>
          match fields.get("exhausted") {
            Some(Number(limit, ..)) => Some(Exhausted(limit=limit.to_int()))
            _ => Some(Refused(reason=@moonjson.dumps(json)))
          }
        _ => Some(Refused(reason=@moonjson.dumps(json)))
      }
    None => None
  }
}

///|
/// An agent: a runtime, the graph its strategy compiled to, and the operations a caller runs.
///
/// The graph is the same engine a plain state machine uses — an agent is a graph whose nodes
/// happen to talk to a model, which is what keeps checkpoints, interrupts, resumption and
/// multi-agent composition available without a second mechanism.
pub struct Agent {
  runtime : Runtime
  graph : @moonstate.Graph[AgentState, Update]
  strategy_name : String
  /// The saver the graph was compiled with, kept so a caller can move a thread's head back to
  /// an earlier checkpoint. `None` when the run has nowhere to keep them.
  saver : &@moonstate.Saver?
}

///|
/// The runtime an agent runs on — what a composed strategy or a protocol adapter needs in order
/// to add nodes of its own.
pub fn Agent::runtime(self : Agent) -> Runtime {
  self.runtime
}

///|
/// The agent's name.
pub fn Agent::name(self : Agent) -> String {
  self.runtime.name
}

///|
/// The compiled graph, for a strategy that composes this agent as a node of its own.
pub fn Agent::graph(self : Agent) -> @moonstate.Graph[AgentState, Update] {
  self.graph
}

///|
/// The strategy it runs.
pub fn Agent::strategy_name(self : Agent) -> String {
  self.strategy_name
}

///|
/// The model it calls.
pub fn Agent::model(self : Agent) -> String {
  self.runtime.model
}

///|
/// Build an agent. The strategy defaults to [`single_run`]; tools from the config are installed
/// first, then whatever the middleware contributes, so a middleware can replace a default tool
/// of the same name.
pub fn create_agent(
  provider : &@moonmuse.Provider,
  config : AgentConfig,
  saver? : &@moonstate.Saver,
  store? : &@moonstate.Store,
  executor? : &@moonstate.Executor,
) -> Agent raise @moonstate.Refused {
  let tools = Tools::new()
  for spec in config.tools {
    tools.add(spec)
  }
  let runtime : Runtime = {
    name: config.name,
    provider,
    model: config.model,
    instructions: config.instructions,
    tools,
    options: config.options,
    limits: config.limits,
    middleware: config.middleware,
    events: config.events,
    structured: config.structured,
    chooser: None,
    exit_tool: config.exit_tool,
    missing_tools: config.missing_tools,
    custom: config.nodes,
    nodes: [],
  }
  install_tools(runtime)
  let strategy = config.strategy.unwrap_or(single_run())
  let graph = strategy.compile(runtime, saver?, store?, executor?)
  { runtime, graph, strategy_name: strategy.name, saver, }
}

///|
/// Run the agent on `input` and return its answer.
///
/// `thread` names the run's checkpoint thread: passing the same name again resumes from what was
/// checkpointed, which is what makes a durable agent possible without a separate API.
pub async fn Agent::run(
  self : Agent,
  input : String,
  thread? : String,
) -> String raise AgentError {
  let goal = Append([@moonmuse.Message::user(input)])
  self.walk(goal, input, thread?)
}

///|
/// The id a checkpoint gets: `cp-` and the sequence number padded to six digits, which is the
/// shape the engine writes so that ids sort the way the checkpoints were written.
fn checkpoint_id(seq : Int32) -> String {
  let digits = seq.to_string()
  let padding = String::make(
    if 6 > digits.length() {
      6 - digits.length()
    } else {
      0
    },
    '0',
  )
  "cp-" + padding + digits
}

///|
/// Move a thread's head back to the checkpoint `id`, so the next `continue_run` picks the run up
/// where that checkpoint left it.
///
/// The target is copied forward as the thread's newest checkpoint instead of deleting the ones
/// after it: a saver here is append-only, and `history` stays a record of what actually
/// happened, including the branch that was abandoned.
pub async fn Agent::rewind(
  self : Agent,
  thread : String,
  id : String,
) -> Unit raise AgentError {
  let saver = match self.saver {
    Some(saver) => saver
    None =>
      raise Refused(
        reason="rewind: this agent was built without a saver, so it has no checkpoints to go back to",
      )
  }
  let read = Ok(saver.get(thread, id~)) catch { error => Err(error) }
  let target = match read {
    Ok(Some(checkpoint)) => checkpoint
    Ok(None) =>
      raise Refused(
        reason="rewind: no checkpoint " + id + " on thread " + thread,
      )
    Err(_) =>
      raise Refused(reason="rewind: the saver could not read thread " + thread)
  }
  let newest = Ok(saver.get(thread)) catch { error => Err(error) }
  let latest = match newest {
    Ok(Some(checkpoint)) => checkpoint
    Ok(None) => target
    Err(_) => target
  }
  let seq = latest.seq + 1
  let record : @moonstate.Checkpoint = {
    thread,
    id: checkpoint_id(seq),
    parent: Some(latest.id),
    seq,
    step: target.step,
    state: target.state,
    pending: target.pending,
    interrupt: None,
    created_at: latest.created_at + 1,
    writes: None,
  }
  let written = Ok(saver.put(record)) catch { error => Err(error) }
  match written {
    Ok(_) => ()
    Err(_) =>
      raise Refused(reason="rewind: the saver could not write thread " + thread)
  }
}

///|
/// Continue a thread from its latest checkpoint without adding a turn to the conversation.
///
/// This is what a rewound thread needs: the checkpoint says which nodes were about to run, and
/// the run picks up there. It is also what a caller uses after a run stopped on a cap, when the
/// input that started the thread has already been read.
pub async fn Agent::continue_run(
  self : Agent,
  thread : String,
) -> String raise AgentError {
  self.walk(Spend(model_calls=0, tool_calls=0), "", thread~)
}

///|
/// Resume an interrupted run with the answer to the question it stopped on.
pub async fn Agent::resume_from(
  self : Agent,
  thread : String,
  answer : Json,
) -> String raise AgentError {
  let runtime = self.runtime
  let walked = Ok(self.graph.resume_with(thread, answer)) catch {
    error => Err(error)
  }
  match walked {
    Ok(state) => self.settle(state)
    Err(error) => {
      (runtime.events.on_agent_execution_failed)(error_text(error))
      runtime.events.report(
        AgentFailed(name=runtime.name, reason=error_text(error)),
      )
      raise Engine(error)
    }
  }
}

///|
/// Run and report each graph event to `listener`, which is how a caller watches a run as it
/// happens rather than after it ends.
pub async fn Agent::stream(
  self : Agent,
  input : String,
  listener : (Event) -> Unit,
  thread? : String,
) -> String raise AgentError {
  let runtime = self.runtime
  let previous = runtime.events.listener
  runtime.events.listener = event => {
    previous(event)
    listener(event)
  }
  let goal = Append([@moonmuse.Message::user(input)])
  let result = self.walk(goal, input, thread?)
  runtime.events.listener = previous
  result
}

///|
/// The walk itself: run the graph, then turn the state it settled on into an answer or an error.
async fn Agent::walk(
  self : Agent,
  goal : Update,
  input : String,
  thread? : String,
) -> String raise AgentError {
  let runtime = self.runtime
  (runtime.events.on_agent_starting)(input)
  (runtime.events.on_strategy_starting)(self.strategy_name)
  runtime.events.report(AgentStarted(name=runtime.name))
  let walked = Ok(self.graph.run(goal, thread?)) catch { error => Err(error) }
  match walked {
    Ok(state) => self.settle(state)
    Err(error) => {
      (runtime.events.on_agent_execution_failed)(error_text(error))
      runtime.events.report(
        AgentFailed(name=runtime.name, reason=error_text(error)),
      )
      raise Engine(error)
    }
  }
}

///|
/// Read the state a run ended on: its text, or the error a node recorded.
fn Agent::settle(self : Agent, state : AgentState) -> String raise AgentError {
  let runtime = self.runtime
  match recorded_failure(state) {
    Some(error) => {
      (runtime.events.on_agent_execution_failed)(describe(error))
      runtime.events.report(
        AgentFailed(name=runtime.name, reason=describe(error)),
      )
      raise error
    }
    None => {
      let text = state.text()
      (runtime.events.on_strategy_completed)(self.strategy_name, text)
      (runtime.events.on_agent_completed)(text)
      runtime.events.report(AgentFinished(name=runtime.name, text~))
      text
    }
  }
}

///|
/// A failure as a line of text, for hooks that only report.
pub fn describe(error : AgentError) -> String {
  match error {
    Exhausted(limit~) => "a cap of " + limit.to_string() + " was reached"
    Refused(reason~) => reason
    Engine(error) => error_text(error)
  }
}

///|
/// The state of a thread, when one was checkpointed.
pub async fn Agent::state(
  self : Agent,
  thread : String,
) -> @moonstate.Snapshot[AgentState]? raise AgentError {
  self.graph.state(thread) catch {
    error => raise Engine(error)
  }
}

///|
/// Every checkpoint of a thread, in the order they were written.
pub async fn Agent::history(
  self : Agent,
  thread : String,
) -> Array[@moonstate.Snapshot[AgentState]] raise AgentError {
  self.graph.history(thread) catch {
    error => raise Engine(error)
  }
}