moonbitstack/moonkoog/middleware does not have a README file

    ContextEditing

    pub struct ContextEditing {
    strategy : EditingStrategy
    }

    Trim a conversation without asking the model to summarise it.

    Cheap and lossless in structure: nothing is invented, so nothing can be wrong. It is the right policy when the older turns are scaffolding — tool results the model has already used — rather than decisions worth keeping.

    ContextEditing::install

    ContextEditing::name

    fn ContextEditing::name(_self : ContextEditing) -> String

    ContextEditing::new

    Trim per strategy.

    EditingStrategy

    pub(all) enum EditingStrategy {
    ClearToolResults(keep~ : Int)
    KeepLast(keep~ : Int)
    }

    How a conversation is trimmed when it is too long.

    Fallback

    pub(all) struct Fallback {
    provider : &
    Provider

    model : String
    }

    One alternative to fall back to: another provider, another model, or both.

    Fallback::new

    fn Fallback::new(provider : &
    Provider
    , model : String) -> Fallback

    A fallback to model on provider.

    FileSearch

    pub struct FileSearch {
    root : String
    limit : Int
    read_limit : Int
    }

    Give the model a way to look around a directory tree.

    Two tools, both read-only: search_files expands a glob under the root, and read_file opens one file. The root is the whole of the permission model — a path that leaves it is refused before anything is opened, which is what keeps a prompt-injected instruction from reading the host's files.

    FileSearch::install

    FileSearch::name

    fn FileSearch::name(_self : FileSearch) -> String

    FileSearch::new

    fn FileSearch::new(root : String, limit? : Int, read_limit? : Int) -> FileSearch

    A search rooted at root, returning at most limit paths and at most read_limit characters of any one file.

    HumanInTheLoop

    pub struct HumanInTheLoop {
    tools : Array[String]
    reason : String
    }

    Ask the host whether a tool may run, by stopping the run on a question.

    The run stops at the tool call; the host answers with true or false when it resumes. An approval is remembered for the rest of the thread, so a tool called five times asks once. A denial comes back to the model as a failed call, which lets it choose another way instead of ending the run.

    HumanInTheLoop::install

    HumanInTheLoop::name

    fn HumanInTheLoop::name(_self : HumanInTheLoop) -> String

    HumanInTheLoop::new

    fn HumanInTheLoop::new(tools : Array[String], reason? : String) -> HumanInTheLoop

    Ask before running any of tools.

    ModelCallLimit

    pub struct ModelCallLimit {
    limit : Int
    }

    Stop a run before it makes more model calls than the budget allows.

    The cap is checked against what the run has already spent, which the state carries, so a resumed run does not get a fresh budget. Reaching it ends the run with a line of text saying so rather than failing: a caller that wanted an error can look at the answer.

    ModelCallLimit::install

    ModelCallLimit::name

    fn ModelCallLimit::name(_self : ModelCallLimit) -> String

    ModelCallLimit::new

    fn ModelCallLimit::new(limit? : Int) -> ModelCallLimit

    A cap of limit model calls per run.

    ModelFallback

    pub struct ModelFallback {
    entries : Array[Fallback]
    }

    Try the alternatives in order when the primary model call fails.

    The order is the point: a smaller local model first, a larger one second, and the primaries' own retry policy already applied inside. Fallbacks call their provider directly — a fallback is a different endpoint, not the same one with different arguments — so the middleware inside them is skipped deliberately.

    ModelFallback::install

    ModelFallback::name

    fn ModelFallback::name(_self : ModelFallback) -> String

    ModelFallback::new

    fn ModelFallback::new(entries : Array[Fallback]) -> ModelFallback

    Fall back to entries in order.

    ModelRetry

    pub struct ModelRetry {
    attempts : Int
    base_ms : Int
    factor : Double
    cap_ms : Int
    }

    Retry a model call that failed in a way the provider itself calls retryable: a rate limit, a gateway error, a timeout. A rejected request is not retried, because the same request would be rejected again.

    ModelRetry::install

    fn ModelRetry::install(_self : ModelRetry, _tools :
    Tools
    ) -> Unit

    ModelRetry::name

    fn ModelRetry::name(_self : ModelRetry) -> String

    ModelRetry::new

    fn ModelRetry::new(attempts? : Int, base_ms? : Int, factor? : Double, cap_ms? : Int) -> ModelRetry

    Retry up to attempts times, waiting the base delay and then growing it by the factor.

    Pii

    pub struct Pii {
    rules : Array[PiiRule]
    action : PiiAction
    }

    Scrub personal data out of what the model is about to read.

    The rules run over the request as it is being sent, so the conversation the run keeps is untouched: a later step still has the real value if the host put it there, while the provider never sees it. Rules are regular expressions, which is what makes them auditable — the policy is data a reviewer can read.

    Pii::install

    fn Pii::install(_self : Pii, _tools :
    Tools
    ) -> Unit

    Pii::name

    fn Pii::name(_self : Pii) -> String

    Pii::new

    fn Pii::new(rules : Array[PiiRule], action? : PiiAction) -> Pii

    Scrub with rules, redacting by default.

    Pii::standard

    fn Pii::standard() -> Pii

    Scrub with the standard recognisers.

    PiiAction

    pub(all) enum PiiAction {
    Redact
    Mask
    }

    What to do with a value a policy recognises as personal data.

    PiiRule

    pub(all) struct PiiRule {
    pattern : String
    label : String
    }

    One recogniser: a regular expression and the label that stands in for what it matches.

    PiiRule::new

    fn PiiRule::new(pattern : String, label : String) -> PiiRule

    A rule matching pattern, replaced with label.

    PiiRule::standard

    fn PiiRule::standard() -> Array[PiiRule]

    The recognisers a policy is usually made of: email addresses, phone numbers, card numbers and national identifiers.

    ShellTool

    pub struct ShellTool {
    prefix : Array[String]
    cwd : String?
    timeout_ms : Int
    }

    Give the model a shell.

    A shell is the broadest capability a run can have, so the tool is explicit about where it runs: the middleware carries the working directory it is allowed in, the shell it hands the line to, and the wall-clock limit after which the process is stopped. Output is cut so one command cannot flood the conversation.

    ShellTool::install

    fn ShellTool::install(self : ShellTool, tools :
    Tools
    ) -> Unit

    ShellTool::name

    fn ShellTool::name(_self : ShellTool) -> String

    ShellTool::new

    fn ShellTool::new(prefix? : Array[String], cwd? : String, timeout_ms? : Int) -> ShellTool

    A shell tool using prefix (program and its arguments, e.g. ["sh", "-c"]), rooted at cwd.

    Summarization

    pub struct Summarization {
    max_messages : Int
    keep : Int
    }

    Fold a conversation that has grown past a limit into a summary before sending it.

    The budget is counted in messages rather than tokens: a message count is exact on every provider, needs no tokenizer, and is what a caller can reason about. The newest messages are kept word for word, because that is what the next step depends on.

    Summarization::install

    Summarization::name

    fn Summarization::name(_self : Summarization) -> String

    Summarization::new

    fn Summarization::new(max_messages? : Int, keep? : Int) -> Summarization

    Summarise once a conversation holds more than max_messages messages, keeping the last keep of them.

    TodoList

    pub struct TodoList {
    }

    Give the model a todo list it can write to.

    A long task goes better when the model states its plan and updates it: the list is in the conversation, so the next step sees it, and in the state, so a resumed run sees it too. The middleware contributes both the tool and the note that tells the model to use it.

    TodoList::install

    fn TodoList::install(_self : TodoList, tools :
    Tools
    ) -> Unit

    TodoList::name

    fn TodoList::name(_self : TodoList) -> String

    TodoList::new

    fn TodoList::new() -> TodoList

    The todo middleware.

    ToolCallLimit

    pub struct ToolCallLimit {
    limit : Int
    tool : String?
    }

    Stop a run from executing more tool calls than the budget allows, in total or for one tool.

    A refused call comes back to the model as a failure rather than ending the run: the model can then answer with what it has, which is usually better than ending mid-task.

    ToolCallLimit::install

    ToolCallLimit::name

    fn ToolCallLimit::name(_self : ToolCallLimit) -> String

    ToolCallLimit::new

    fn ToolCallLimit::new(limit? : Int, tool? : String) -> ToolCallLimit

    A cap of limit executions, of one tool when tool is given and of all of them otherwise.

    ToolRetry

    pub struct ToolRetry {
    attempts : Int
    base_ms : Int
    factor : Double
    cap_ms : Int
    }

    Retry a tool call that failed. Whether a failure is worth another attempt is the tool's business — a network read is, a rejected argument is not — so the policy looks at the reason the tool gave and retries everything unless told otherwise.

    ToolRetry::install

    fn ToolRetry::install(_self : ToolRetry, _tools :
    Tools
    ) -> Unit

    ToolRetry::name

    fn ToolRetry::name(_self : ToolRetry) -> String

    ToolRetry::new

    fn ToolRetry::new(attempts? : Int, base_ms? : Int, factor? : Double, cap_ms? : Int) -> ToolRetry

    Retry up to attempts times with the same growth as a model retry.

    ToolSelection

    pub struct ToolSelection {
    max_tools : Int
    always : Array[String]
    }

    Pick the tools worth advertising for the next call.

    A large toolbox costs tokens on every request and confuses a small model. This middleware asks the model, once per call, which of the named tools it needs for what the user just asked, and advertises only those — always keeping the ones a policy pins.

    ToolSelection::install

    ToolSelection::name

    fn ToolSelection::name(_self : ToolSelection) -> String

    ToolSelection::new

    fn ToolSelection::new(max_tools? : Int, always? : Array[String]) -> ToolSelection

    Advertise at most max_tools tools, chosen per call, plus every tool in always.

    cleared

    let cleared : String

    What stands in for a cleared tool result.

    format_todos

    fn format_todos(items : Array[
    Json
    ]) -> String

    The list as the model reads it back: one line per item, with its status.

    os_shell

    let os_shell : Array[String]

    The shell a command line is handed to. Windows has no sh, so a cmd.exe install is used there; everywhere else the POSIX shell is the one a caller expects.

    read_tool

    let read_tool : String

    search_tool

    let search_tool : String

    The tools the middleware installs.

    shell_tool

    let shell_tool : String

    The tool the middleware installs.

    todo_key

    let todo_key : String

    The storage key the list lives under.

    todo_note

    let todo_note : String

    What the model is told about the list, once, at the start of the run.

    todo_tool

    let todo_tool : String

    The tool the middleware installs.

    todos

    The list a run recorded, when it has one.

    tool_count

    fn tool_count(state :
    AgentState
    , name : String) -> Int

    How many times a tool has run in this thread so far. The tool node records it after each round, which is why the count survives a checkpoint.