harn-stdlib 0.10.201

Embedded Harn standard library source catalog
Documentation
import { AgentToolBatchPhase } from "std/agent/events"
import { agent_tool_annotations } from "std/agent/tool_annotations"
import { __tool_registry_name } from "std/llm/call_shape"
import { ToolRegistry } from "std/tools"

const OBSERVATIONS = ["read", "search", "think", "fetch", "inspect", "list"]

const MUTATIONS = ["edit", "write", "scaffold", "delete", "move", "mutation", "mutate"]

const PROCESSES = [
  "execute",
  "process",
  "verify",
  "verification",
  "verify_completion",
  "test",
  "check",
  "command",
]

const TERMINALS = ["terminal", "done", "complete", "completion"]

const MUTATING_EFFECTS = ["workspace", "workspace_write", "network", "desktop_control"]

pub type ToolBatchCallClassification = {
  phase: AgentToolBatchPhase,
  declared_mutation: bool,
  declared_verification: bool,
}

fn classification(
  phase: AgentToolBatchPhase,
  mutation: bool = false,
  verification: bool = false,
) -> ToolBatchCallClassification {
  return {phase: phase, declared_mutation: mutation, declared_verification: verification}
}

fn annotation_text(value: unknown) -> string {
  return lowercase(trim(to_string(value ?? "")))
}

fn process_is_read_effect(args: dict) -> bool {
  const command = args?.command ?? args?.cmd ?? args?.script
  const argv = args?.argv
  const has_command = command != nil && to_string(command) != ""
  const has_argv = type_of(argv) == "list" && len(argv) > 0
  if !has_command && !has_argv {
    return false
  }
  const request = has_argv ? {mode: "argv", argv: argv, command: to_string(command ?? "")} : {
    mode: "shell",
    command: to_string(command),
  }
  const classified = try {
    command_workspace_effect({request: request})
  }
  return is_ok(classified) && unwrap(classified)?.effect == "read_effect"
}

/**
 * Classify resolved registry facts once; sibling order does not imply dependency.
 * @effects: []
 * @errors: []
 */
pub fn tool_batch_classify(
  args: dict,
  entry: dict?,
  annotations: dict,
  explicit_terminal: bool,
) -> ToolBatchCallClassification {
  const nested: dict = entry?.function ?? {}
  const executor = annotation_text(entry?.executor ?? nested?.executor)
  const kind = annotation_text(annotations?.kind ?? annotations?.tool_kind ?? annotations?.toolKind)
  const side_effect = annotation_text(
    annotations?.side_effect_level ?? annotations?.sideEffectLevel
      ?? annotations?.side_effect
      ?? annotations?.sideEffect,
  )
  const mutation = annotation_text(
    annotations?.mutation_classification ?? annotations?.mutationClassification
      ?? annotations?.mutation,
  )
  const mutation_declared = (annotations?.destructiveHint ?? false)
    || MUTATIONS.contains(kind)
    || mutation == "workspace_write"
  const mutating_effect = MUTATING_EFFECTS.contains(side_effect)
  if executor == "provider_native" {
    return classification("provider_native")
  }
  if (annotations?.terminal ?? false) || TERMINALS.contains(kind) || explicit_terminal {
    return classification("terminal")
  }
  if annotations?.completion_evidence_role == "verification" && side_effect == "process_exec"
    && !mutation_declared
    && !mutating_effect {
    return classification("process_verification", false, true)
  }
  if !mutation_declared
    && (annotations?.readOnlyHint ?? annotations?.read_only_hint ?? false) {
    return classification("observation")
  }
  if !mutation_declared
    && (OBSERVATIONS.contains(kind) || side_effect == "none" || side_effect == "read_only")
    && !mutating_effect {
    return classification("observation")
  }
  if PROCESSES.contains(kind) || side_effect == "process_exec" {
    return classification(process_is_read_effect(args) ? "observation" : "process_verification")
  }
  return classification("mutation", mutation_declared || mutating_effect)
}

/**
 * Rank the declared dependency phases, independently of sibling source order.
 * @effects: []
 * @errors: []
 */
pub fn tool_batch_phase_rank(phase: AgentToolBatchPhase) -> int {
  match phase {
    "provider_native" -> { return 0 }
    "observation" -> { return 1 }
    "mutation" -> { return 2 }
    "process_verification" -> { return 3 }
    "terminal" -> { return 4 }
  }
}

/**
 * A single fixed phase cannot retain a later phase. Process arguments can
 * select observation or verification, so their registry stays resolution-capable.
 * @effects: []
 * @errors: []
 */
pub fn tool_batch_registry_can_retain(
  tools: ToolRegistry,
  policy: dict?,
  terminal_tools: list<string>,
) -> bool {
  let phases: list<AgentToolBatchPhase> = []
  for entry in tools.tools {
    const name = __tool_registry_name(entry)
    const annotations = agent_tool_annotations(entry, policy, name)
    const classified = tool_batch_classify({}, entry, annotations, contains(terminal_tools, name))
    if classified.phase == "process_verification" && !classified.declared_verification {
      return true
    }
    if !phases.contains(classified.phase) {
      phases.push(classified.phase)
    }
  }
  return len(phases) > 1
}