/** @module
  @summary Helpers every std::agents worker uses: context folding and model
  overrides.
*/

export def withContext(task: string, context: string): string {
  """
  Fold optional context material into a task prompt. Returns the task
  unchanged when no context is given.

  @param task - The task text
  @param context - Extra material, or "" for none
  """
  return if context == "" then task else "${task}\n\n<context>\n${context}\n</context>"
}

export type ReasoningEffort = "low" | "medium" | "high"

export def llmOptions(
  model: string,
  provider: string,
  tools: any[] = [],
  hostedTools: string[] = [],
  reasoningEffort: ReasoningEffort | null = null,
  thinking: boolean = false,
): any {
  """
  Build an llm options object with an optional model override. Returns a
  fresh object every call and never mutates its arguments. The model and
  provider fields are only set when a model is named, so an empty override
  never clobbers the default model.

  @param model - Model name, or "" for the ambient model
  @param provider - Provider for the model, or "" to auto-resolve
  @param tools - Tools to offer the LLM
  @param hostedTools - Provider-hosted tools to enable
  @param reasoningEffort - Reasoning effort to request from the model, or null for none
  @param thinking - Whether to enable thinking mode, which allows the model to use more time and tokens to reason about its answer
  """
  const options: any = {
    tools: tools
  }
  if (hostedTools.length > 0) {
    options.hostedTools = hostedTools
  }
  if (model != "") {
    options.model = model
    options.provider = provider
  }
  if (reasoningEffort != null) {
    options.reasoningEffort = reasoningEffort
  }
  if (thinking) {
    options.thinking = {
      enabled: true
    }
  }
  return options
}