///|
/// The node an agent run starts from: it seeds the system message, runs the middleware's
/// run-start hooks, and hands over to the model node.
pub let agent_node : String = "agent"

///|
/// The node that makes one model call.
pub let model_node : String = "model"

///|
/// The node that executes the calls a reply asked for.
pub let tools_node : String = "tools"

///|
/// The node a run ends on.
pub let finish_node : String = "finish"

///|
/// Which way a request node asks the model.
///
/// This is the whole of the request side: the many request nodes a Kotlin-style DSL spells out
/// separately differ only in what they put in the request — the tools, the choice, the number
/// of candidates, whether the answer is streamed or shaped by a schema.
pub(all) enum RequestMode {
  /// Advertise the toolbox and let the model decide.
  Tools
  /// Advertise nothing, for a turn that must answer in prose.
  NoTools
  /// Advertise the toolbox and require a call.
  OnlyCalling
  /// Advertise the toolbox and require the named tool.
  ForceOne(String)
  /// Ask `count` times and keep the candidate the chooser prefers.
  Choice(Int32)
  /// Stream the reply, reporting deltas to the event handler.
  Streaming
  /// Answer as an object matching the agent's structured-output schema.
  StructuredOutput
}

///|
/// Which calls an execution node runs.
pub(all) enum ExecuteMode {
  /// Every call in the reply.
  All
  /// Only the call at this position, for a run that executes calls one at a time.
  Single(Int32)
}

///|
/// Which part of the conversation a compression node folds into a summary.
pub(all) enum HistoryPolicy {
  Whole
  FromLast(Int32)
}

///|
/// One position in a strategy graph.
///
/// Four kinds cover the twenty-six node functions the graph DSL of the framework this one is
/// designed after exposes: every request variant is one `Request` mode, every tool-result
/// variant folds into the request that follows it, tool execution is one node, history
/// compression and the exit are one each. The moderation nodes are a middleware here, because
/// what they do — inspect or rewrite messages on the way through — is a pipeline concern.
pub(all) enum NodeKind {
  /// The run-start node: seeds the system message, runs the middleware's start hooks, and
  /// hands over to the node the strategy puts after it.
  Start(then~ : String)
  Request(RequestMode)
  Execute(ExecuteMode)
  Compress(HistoryPolicy)
  Finish
  /// Reason without tools, every `every` rounds of the run.
  Think(prompt~ : String, every~ : Int32)
  /// Add a message and ask again — how a strategy nudges the model.
  Advise(String)
  /// A body the caller registered on the runtime.
  Custom(String)
  /// A request whose prose answer goes to `then` rather than ending the run — how a
  /// plan-and-execute loop advances a step instead of stopping on the first paragraph.
  Turn(mode~ : RequestMode, then~ : String)
  /// Another agent, run as a nested graph over the same conversation.
  Delegate(@moonstate.Graph[AgentState, Update])
}

///|
/// The request this node sends: the conversation so far, the tools the mode allows, and the
/// agent's options.
pub fn Runtime::request_for(
  self : Runtime,
  mode : RequestMode,
  state : AgentState,
) -> @moonmuse.Request {
  let tools = match mode {
    NoTools | StructuredOutput => []
    _ => self.tool_specs()
  }
  let choice = match mode {
    OnlyCalling => @moonmuse.ToolChoice::Required
    ForceOne(name) => @moonmuse.ToolChoice::Named(name)
    _ => self.options.choice
  }
  // The conversation as this agent can read it: with a converting policy, parts naming tools it
  // does not offer are replaced by text before they reach the provider.
  let messages = convert_missing_tools(
    state.messages,
    self.tools.specs().map(spec => spec.tool.name),
    self.missing_tools,
  )
  let stop = self.options.stop
  let extra = self.options.extra
  match (self.options.temperature, self.options.max_tokens) {
    (Some(temperature), Some(max_tokens)) =>
      @moonmuse.Request::new(
        self.model,
        messages,
        tools~,
        choice~,
        temperature~,
        max_tokens~,
        stop~,
        extra~,
      )
    (Some(temperature), None) =>
      @moonmuse.Request::new(
        self.model,
        messages,
        tools~,
        choice~,
        temperature~,
        stop~,
        extra~,
      )
    (None, Some(max_tokens)) =>
      @moonmuse.Request::new(
        self.model,
        messages,
        tools~,
        choice~,
        max_tokens~,
        stop~,
        extra~,
      )
    (None, None) =>
      @moonmuse.Request::new(
        self.model,
        messages,
        tools~,
        choice~,
        stop~,
        extra~,
      )
  }
}

///|
/// The calls the last assistant message asked for.
fn pending_calls(state : AgentState) -> Array[@moonmuse.Part] {
  let mut index = state.messages.length() - 1
  while index >= 0 {
    let message = state.messages[index]
    if message.role is Assistant {
      return message.calls()
    }
    index = index - 1
  }
  []
}

///|
/// End the run with a recorded failure. The walk stops at the finish node and `Agent::run`
/// turns the record into the error it raises.
fn failed(reason : String) -> Array[@moonstate.Step[AgentState, Update]] {
  [
    @moonstate.Step::Write(Store(key=error_key, value=Json::string(reason))),
    @moonstate.Step::Goto(finish_node),
  ]
}

///|
/// End the run because a cap was reached, with the cap that stopped it.
fn exhausted(limit : Int32) -> Array[@moonstate.Step[AgentState, Update]] {
  [
    @moonstate.Step::Write(
      Store(
        key=error_key,
        value=Json::object(
          Map([("exhausted", Json::number(limit.to_double()))]),
        ),
      ),
    ),
    @moonstate.Step::Goto(finish_node),
  ]
}

///|
/// The run-start node.
pub async fn node_agent(
  runtime : Runtime,
  then : String,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  // A new turn starts clean: the failure the last turn recorded, if any, is not this turn's.
  let steps : Array[@moonstate.Step[AgentState, Update]] = [
    @moonstate.Step::Write(Forget(key=error_key)),
  ]
  match runtime.instructions {
    Some(instructions) =>
      if !has_system_message(state.messages) {
        let messages = [@moonmuse.Message::system(instructions)]
        for message in state.messages {
          messages.push(message)
        }
        steps.push(@moonstate.Step::Write(Replace(messages)))
      }
    None => ()
  }
  let context = runtime.context(run, state)
  for update in before_agent_hooks(runtime, context) {
    steps.push(@moonstate.Step::Write(update))
  }
  steps.push(@moonstate.Step::Goto(then))
  steps
}

///|
/// Whether the conversation already opens with a system message.
fn has_system_message(messages : Array[@moonmuse.Message]) -> Bool {
  for message in messages {
    if message.role is System {
      return true
    }
  }
  false
}

///|
/// The model node: one call, then route on what came back.
pub async fn node_request(
  runtime : Runtime,
  mode : RequestMode,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  node_request_to(runtime, mode, finish_node, state, run)
}

///|
/// The model node with a different destination for a prose answer.
pub async fn node_request_to(
  runtime : Runtime,
  mode : RequestMode,
  then : String,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  if state.model_calls >= runtime.limits.iterations {
    return exhausted(runtime.limits.iterations)
  }
  let context = runtime.context(run, state)
  runtime.events.report(ModelStarted(name=runtime.name, model=runtime.model))
  let outcome = match mode {
    Choice(count) => choose_reply(runtime, context, state, mode, count)
    _ => {
      let request = runtime.request_for(mode, state)
      let call : ModelCall = { request, }
      pipeline_model(runtime, context, call, mode)
    }
  }
  match outcome {
    Replied(reply) => {
      runtime.events.report(ModelFinished(name=runtime.name, usage=reply.usage))
      let calls = reply.calls()
      let steps : Array[@moonstate.Step[AgentState, Update]] = [
        @moonstate.Step::Write(Append([reply.message])),
        @moonstate.Step::Write(Spend(model_calls=1, tool_calls=0)),
      ]
      for update in context.pending {
        steps.push(@moonstate.Step::Write(update))
      }
      if calls.length() > 0 {
        steps.push(@moonstate.Step::Goto(tools_node))
      } else {
        steps.push(@moonstate.Step::Goto(then))
      }
      steps
    }
    Halted(text) =>
      [@moonstate.Step::Write(Answer(text)), @moonstate.Step::Goto(finish_node)]
    Failed(reason~, ..) => failed(reason)
  }
}

///|
/// Ask `count` times, then keep the candidate the agent's chooser prefers.
async fn choose_reply(
  runtime : Runtime,
  context : RunContext,
  state : AgentState,
  mode : RequestMode,
  count : Int32,
) -> ModelOutcome {
  let candidates : Array[@moonmuse.Reply] = []
  let rounds = if count > 0 { count } else { 1 }
  for _ in 0.. candidates.push(reply)
      Halted(text) => return Halted(text)
      Failed(reason~, retryable~) => return Failed(reason~, retryable~)
    }
  }
  match runtime.chooser {
    Some(chooser) => {
      let reply = chooser.choose(candidates)
      Replied(reply)
    }
    None =>
      match candidates {
        [first, ..] => Replied(first)
        [] =>
          Replied(
            @moonmuse.Reply::new(
              @moonmuse.Message::assistant(""),
              finish=@moonmuse.Finish::Stop,
            ),
          )
      }
  }
}

///|
/// The tool node: run the calls, feed the results back, and route to the next agent when a tool
/// asked for a handover.
pub async fn node_execute(
  runtime : Runtime,
  mode : ExecuteMode,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  let calls = pending_calls(state)
  let context = runtime.context(run, state)
  let results : Array[@moonmuse.Part] = []
  let counts : Map[String, Int32] = Map([])
  let mut executed = 0
  if state.tool_calls >= runtime.limits.tool_calls {
    return exhausted(runtime.limits.tool_calls)
  }
  for index, part in calls {
    let selected = match mode {
      All => true
      Single(at) => at == index
    }
    if selected {
      match part {
        @moonmuse.Part::Call(id~, name~, args~) => {
          runtime.events.report(ToolStarted(name~, call_id=id))
          let args = (runtime.events.on_tool_call_starting)(name, args)
          let call : ToolCall = {
            part: @moonmuse.Part::Call(id~, name~, args~),
          }
          let (content, failed) = match pipeline_tool(runtime, context, call) {
            Done(content) => (content, false)
            Failed(reason) => (reason, true)
            Suspend(value) => return [@moonstate.Step::Interrupt(value)]
          }
          let content = (runtime.events.on_tool_call_completed)(name, content)
          if failed {
            (runtime.events.on_tool_call_failed)(name, content)
          }
          runtime.events.report(ToolFinished(name~, call_id=id, failed~))
          results.push(@moonmuse.Part::result(id, content, error=failed))
          counts[name] = counts.get(name).unwrap_or(0) + 1
          executed = executed + 1
        }
        _ => ()
      }
    }
  }
  let steps : Array[@moonstate.Step[AgentState, Update]] = [
    @moonstate.Step::Write(Append([@moonmuse.Message::new(Tool, results)])),
    @moonstate.Step::Write(Spend(model_calls=0, tool_calls=executed)),
  ]
  for name, added in counts {
    let key = "moonkoog.tool_count." + name
    let base = match state.storage.get(key) {
      Some(Number(value, ..)) => value.to_int()
      _ => 0
    }
    steps.push(
      @moonstate.Step::Write(
        Store(key~, value=Json::number((base + added).to_double())),
      ),
    )
  }
  for update in context.pending {
    steps.push(@moonstate.Step::Write(update))
  }
  match runtime.exit_tool {
    Some(exit_tool) =>
      if called_tool(calls, exit_tool) {
        steps.push(@moonstate.Step::Write(Answer("Chat finished")))
        steps.push(@moonstate.Step::Goto(finish_node))
        return steps
      }
    None => ()
  }
  match context.handover.val {
    Some(target) => {
      runtime.events.report(HandedOver(from=runtime.name, to=target))
      if runtime.has_node(target) {
        steps.push(@moonstate.Step::Write(Forget(key=handoff_key)))
        steps.push(@moonstate.Step::Goto(target))
      } else {
        // The agent that asked for the handover is a peer of a team: its own graph has no node
        // for the target, so it ends its turn and the team's router reads the marker.
        steps.push(@moonstate.Step::Goto(finish_node))
      }
    }
    None => steps.push(@moonstate.Step::Goto(model_node))
  }
  steps
}

///|
/// The compression node: replace older messages with a summary the model wrote.
pub async fn node_compress(
  runtime : Runtime,
  policy : HistoryPolicy,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  let context = runtime.context(run, state)
  match compress(runtime, context, state.messages, policy) {
    Done(messages) => [@moonstate.Step::Write(Replace(messages))]
    Refused(reason~) => failed(reason)
  }
}

///|
/// The run-end node: settle the answer, then let the middleware add anything it kept for the
/// end. A node with no successors ends the walk.
pub async fn node_finish(
  runtime : Runtime,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  // The answer is what the model last said. `state.text()` prefers the answer a previous turn
  // recorded, which on a continued thread is the turn before this one.
  let fresh = last_assistant_text(state)
  let answer = if fresh != "" { fresh } else { state.text() }
  let steps : Array[@moonstate.Step[AgentState, Update]] = [
    @moonstate.Step::Write(Answer(answer)),
  ]
  let context = runtime.context(run, state)
  for update in after_agent_hooks(runtime, context, state) {
    steps.push(@moonstate.Step::Write(update))
  }
  steps
}

///|
/// Whether a reply asked for the named tool.
fn called_tool(calls : Array[@moonmuse.Part], name : String) -> Bool {
  for call in calls {
    match call {
      @moonmuse.Part::Call(name=requested, ..) =>
        if requested == name {
          return true
        }
      _ => ()
    }
  }
  false
}

///|
/// The reasoning node: ask the model what it has learned, without tools, and keep its answer in
/// the conversation so the next action is informed by it. Skipped on rounds that are not due.
pub async fn node_think(
  runtime : Runtime,
  state : AgentState,
  run : @moonstate.Run,
  prompt~ : String,
  every~ : Int32,
) -> Array[@moonstate.Step[AgentState, Update]] {
  let interval = if every > 0 { every } else { 1 }
  if state.model_calls % interval != 0 {
    return [@moonstate.Step::Goto(model_node)]
  }
  let context = runtime.context(run, state)
  let seeded_messages = state.messages.copy()
  seeded_messages.push(@moonmuse.Message::user(prompt))
  let seeded = { ..state, messages: seeded_messages, }
  let request = runtime.request_for(RequestMode::NoTools, seeded)
  let call : ModelCall = { request, }
  match pipeline_model(runtime, context, call, RequestMode::NoTools) {
    Replied(reply) =>
      [
        @moonstate.Step::Write(
          Append([@moonmuse.Message::user(prompt), reply.message]),
        ),
        @moonstate.Step::Write(Spend(model_calls=1, tool_calls=0)),
        @moonstate.Step::Goto(model_node),
      ]
    Halted(text) =>
      [@moonstate.Step::Write(Answer(text)), @moonstate.Step::Goto(finish_node)]
    Failed(reason~, ..) => failed(reason)
  }
}

///|
/// A node the caller registered on the runtime, by name.
pub async fn node_custom(
  runtime : Runtime,
  name : String,
  state : AgentState,
  run : @moonstate.Run,
) -> Array[@moonstate.Step[AgentState, Update]] {
  match runtime.custom.get(name) {
    Some(body) => body(runtime, state, run)
    None => failed("no node named \"" + name + "\" is registered")
  }
}