mini-a.yaml

# Author: Nuno Aguiar
help:
  text   : |
    A mini autonomous agent that uses an LLM (use OAF_MODEL environment variable) and shell commands to achieve a specified goal in small steps.

    Examples:
      # Single MCP connection
      ojob mini-a.yaml goal="..." mcp="(cmd: 'docker run --rm -i mcp/dockerhub', timeout: 5000)" rpm=20
      ojob mini-a.yaml goal="..." mcp="(cmd: 'docker run --rm -i mcp/wikipedia-mcp', timeout: 5000)" rpm=20 knowledge="give final answer in markdown"
      
      # Multiple MCP connections
      ojob mini-a.yaml goal="..." mcp="[(cmd: 'docker run --rm -i mcp/dockerhub', timeout: 5000) | (cmd: 'docker run --rm -i mcp/wikipedia-mcp', timeout: 5000)]" rpm=20
      
  expects: 
  - name     : goal
    desc     : Goal for the agent to achieve
    example  : aValueExample
    mandatory: true
  - name     : mcp
    desc     : A MCP connection object (or array of objects) using OpenAF's $mcp() function in SLON or JSON format
    example  : "(url: 'http://127.0.0.1:17879/mcp', type: remote, debug: false)"
    mandatory: false
  - name     : mcplazy
    desc     : Initialize MCP connections lazily on first use instead of during startup
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : verbose
    desc     : Whether to print detailed logs
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : maxsteps
    desc     : Maximum consecutive steps without a successful action before forcing a final response
    example  : "15"
    mandatory: false
  - name     : rpm
    desc     : Maximum number of LLM requests per minute
    example  : "20"
    mandatory: false
  - name     : tpm
    desc     : Maximum number of LLM tokens per minute across prompt and completion
    example  : "80000"
    mandatory: false
  - name     : rtm
    desc     : Legacy alias for rpm (requests per minute)
    example  : "20"
    mandatory: false
  - name     : readwrite
    desc     : Allow read-write commands without confirmation (dangerous)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : checkall
    desc     : Check all commands for banned operations (may ask for confirmation)
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : useshell
    desc     : "Whether to allow shell commands (default: false)"
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : shell
    desc     : Prefix applied to every shell command (requires useshell=true)
    example  : "sandbox-exec -f /path/to/profile.sb"
    mandatory: false
  - name     : usesandbox
    desc     : Enable built-in OS sandbox presets for shell commands (off/auto/linux/macos/windows); warns when unavailable or best-effort
    example  : "auto"
    mandatory: false
  - name     : sandboxprofile
    desc     : Optional macOS sandbox profile path (otherwise Mini-A auto-generates a restrictive temporary .sb profile)
    example  : "/path/to/profile.sb"
    mandatory: false
  - name     : sandboxnonetwork
    desc     : Disable network inside the built-in sandbox when supported (Windows remains best-effort)
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : shelltimeout
    desc     : Maximum shell command execution time in milliseconds before timeout
    example  : "30000"
    mandatory: false
  - name     : shellmaxbytes
    desc     : Maximum shell output size in characters before truncating to a head/tail excerpt
    example  : "12000"
    mandatory: false
  - name     : shellallow
    desc     : Comma-separated list of banned commands to allow explicitly
    example  : "curl,wget"
    mandatory: false
  - name     : shellallowpipes
    desc     : Allow pipes, redirection and shell control operators
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : shellbanextra
    desc     : Additional comma-separated commands to ban
    example  : "lsblk,ifconfig"
    mandatory: false
  - name     : extrahooks
    desc     : Comma-separated list of additional hook directories to load
    example  : "/path/to/hooks1,/path/to/hooks2"
    mandatory: false
  - name     : outfile
    desc     : Output file path to save the final answer (if not provided, prints to console). In deep research mode, only the research output is written here.
    example  : "/path/to/output.txt"
    mandatory: false
  - name     : outfileall
    desc     : "Deep research only: output file path to save the full results (cycle history, verdicts, learnings). If not provided, the full results print to console."
    example  : "/path/to/full-results.md"
    mandatory: false
  - name     : knowledge
    desc     : "Additional knowledge or context to provide to the agent (in the form of a string or a path to a text file)"
    example  : "You have access to a Linux shell and can run commands like ls, cat, grep, wc, curl, etc."
    mandatory: false
  - name     : youare
    desc     : "Override the opening \"You are ...\" persona sentence (string or @file path, alias: youAre) to craft specialized agents"
    example  : "You are a senior firmware analyst focused on reverse engineering embedded devices."
    mandatory: false
  - name     : conversation
    desc     : Conversation history file to provide to the agent
    example  : "/path/to/conversation.json"
    mandatory: false
  - name     : chatyouare
    desc     : "Override the chatbot persona sentence (string or @file path, alias: chatYouAre) when running with chatbotmode=true"
    example  : "You are an enthusiastic travel concierge specialized in eco-friendly trips."
    mandatory: false
  - name     : libs
    desc     : Comma-separated list of additional OJob libraries to load (e.g., "lib1,lib2")
    example  : "lib1,lib2"
    mandatory: false
  - name     : maxcontext
    desc     : "Maximum context size in tokens (default: 0 = disable proactive summarization; recover automatically on provider context-window errors)"
    example  : "200000"
    mandatory: false
  - name     : compressgoal
    desc     : "Boolean to enable/disable automatic compression of oversized goal text before execution (default: false)"
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : compressgoaltokens
    desc     : "Estimated token threshold above which goal compression is considered when compressgoal=true (default: 250)"
    example  : "400"
    mandatory: false
  - name     : compressgoalchars
    desc     : "Character threshold above which goal compression is considered when compressgoal=true (default: 1000)"
    example  : "1500"
    mandatory: false
  - name     : maxcontent
    desc     : Alias for maxcontext
    example  : "0"
    mandatory: false
  - name     : validationgoal
    desc     : Validation criteria for deep research outcomes (string or file path; implies deepresearch=true, defaults maxcycles=3)
    example  : "Validate: includes sources, covers tradeoffs, provides a recommendation"
    mandatory: false
  - name     : valgoal
    desc     : Alias for validationgoal
    example  : "Validate: includes sources, covers tradeoffs, provides a recommendation"
    mandatory: false
  - name     : deepresearch
    desc     : Enable deep research iterative cycles
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : maxcycles
    desc     : "Maximum number of deep research cycles (default: 3)"
    example  : "3"
    mandatory: false
  - name     : validationthreshold
    desc     : Validation verdict label expected to pass deep research validation
    example  : "PASS"
    mandatory: false
  - name     : modelval
    desc     : Override OAF_VAL_MODEL configuration for this run
    example  : "(type: openai, model: gpt-4o-mini, key: '...')"
    mandatory: false
  - name     : persistlearnings
    desc     : Persist deep research learnings between cycles
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : raw
    desc     : Whether to return raw output without formatting
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : showthinking
    desc     : Surface XML-tagged thinking blocks in model responses as thought logs
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : debug
    desc     : Enable debug mode
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : shellbatch
    desc     : Run in batch mode without prompting for command execution approval
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : toolcachettl
    desc     : Default cache TTL in milliseconds for MCP tool results
    example  : "600000"
    mandatory: false
  - name     : usetools
    desc     : Register MCP tools directly on the model instead of expanding the prompt with schemas
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : usetoolslc
    desc     : Register MCP tools directly only on the low-cost model when OAF_LC_MODEL/modellc is configured
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : usejsontool
    desc     : Register an optional compatibility json tool when usetools=true (for models that may emit json tool calls)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : useutils
    desc     : Automatically register Mini Utils Tool utilities as an MCP connection (includes console-only userInput when running mini-a-con)
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : useskills
    desc     : Expose the Mini Utils Tool `skills` operation (only when useutils=true)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : utilsroot
    desc     : Root directory for Mini Utils Tool file operations (only when useutils=true)
    example  : "/path/to/project"
    mandatory: false
  - name     : utilsallow
    desc     : Comma-separated allowlist of Mini Utils Tool names to expose when useutils=true
    example  : "filesystemQuery,markdownFiles"
    mandatory: false
  - name     : utilsdeny
    desc     : Comma-separated denylist of Mini Utils Tool names to hide when useutils=true (applied after utilsallow)
    example  : "systemInfo,textUtilities"
    mandatory: false
  - name     : usediagrams
    desc     : Encourage Mermaid diagrams by priming the agent with diagram guidance
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usemermaid
    desc     : Alias for usediagrams; setting either enables Mermaid diagram guidance
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usecharts
    desc     : Encourage Chart.js outputs by priming the agent with chart guidance
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : useascii
    desc     : Encourage ASCII sketches in the generated knowledge prompt
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usemaps
    desc     : Encourage Leaflet.js interactive maps by priming the agent with map guidance
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usemath
    desc     : Encourage LaTeX math formulas in markdown output for KaTeX rendering
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usesvg
    desc     : Encourage secure raw SVG outputs rendered as data URI images in the web UI
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usevectors
    desc     : Enable vector graphics guidance bundle (usesvg + usediagrams)
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : usestream
    desc     : Enable streaming output - display LLM tokens as they arrive in real-time
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : mcpdynamic
    desc     : Enable dynamic tool selection instead of registering all MCP tools (analyzes goal to select relevant tools)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : mcpproxy
    desc     : Route MCP access through the proxy-dispatch tool
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : mcpproxythreshold
    desc     : Byte threshold to auto-spill large proxy tool results to files (0 disables)
    example  : "0"
    mandatory: false
  - name     : mcpproxytoon
    desc     : When mcpproxythreshold > 0, serialize spilled proxy tool results in TOON format for easier search and lower token usage
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : forceplanning
    desc     : Force planning even when heuristics would normally skip it
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : useplanning
    desc     : Enable task planning updates (agent mode only)
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : planstyle
    desc     : Planning style - simple (flat sequential steps) or legacy (phase-based hierarchical)
    example  : "simple"
    mandatory: false
    options  : ["simple", "legacy"]
  - name     : earlystopthreshold
    desc     : Number of consecutive think/error-like steps before forcing stronger recovery logic
    example  : "3"
    mandatory: false
  - name     : planmode
    desc     : Run Mini-A in plan-only mode (produce or convert plans without executing)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : validateplan
    desc     : Validate a plan using LLM-based critique and structure validation without executing
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : convertplan
    desc     : Convert the loaded/generated plan to the requested format and exit
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : resumefailed
    desc     : Attempt to resume the last failed goal on startup
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : chatbotmode
    desc     : Run Mini-A in conversational chatbot mode without agent planning
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : promptprofile
    desc     : Prompt verbosity profile for system instructions (minimal, balanced, verbose)
    example  : "balanced"
    mandatory: false
    options  : ["minimal", "balanced", "verbose"]
  - name     : systempromptbudget
    desc     : Maximum system prompt size in estimated tokens before Mini-A drops low-priority sections
    example  : "1800"
    mandatory: false
  - name     : rules
    desc     : Custom rules or instructions for the agent (JSON or SLON array of strings)
    example  : '["Always provide detailed explanations", "Use concise language"]'
    mandatory: false
  - name     : state
    desc     : Initial state data to provide to the agent as structured JSON/SLON
    example  : '{"current_task": "analysis", "progress": 0}'
    mandatory: false
  - name     : usedelegation
    desc     : Enable subtask delegation to local/remote workers
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : workers
    desc     : Comma-separated list of worker URLs (http/https) for delegation
    example  : "http://127.0.0.1:17777,http://127.0.0.1:17778"
    mandatory: false
  - name     : workerreg
    desc     : Start worker registration HTTP server on the provided port
    example  : "18888"
    mandatory: false
  - name     : workerregtoken
    desc     : Optional token required by the worker registration endpoint
    example  : "my-shared-token"
    mandatory: false
  - name     : workerevictionttl
    desc     : Worker eviction TTL in milliseconds for stale worker entries
    example  : "60000"
    mandatory: false
  - name     : maxconcurrent
    desc     : Maximum concurrent delegated subtasks
    example  : "4"
    mandatory: false
  - name     : delegationmaxdepth
    desc     : Maximum recursive delegation depth
    example  : "3"
    mandatory: false
  - name     : delegationtimeout
    desc     : Default delegated subtask timeout in milliseconds
    example  : "300000"
    mandatory: false
  - name     : delegationmaxretries
    desc     : Maximum retries per delegated subtask
    example  : "2"
    mandatory: false
  - name     : planfile
    desc     : Plan file path to load or save before execution
    example  : "/path/to/plan.md"
    mandatory: false
  - name     : planformat
    desc     : Plan format override; accepts md or json
    example  : "json"
    mandatory: false
  - name     : plancontent
    desc     : Inline plan definition provided as Markdown or JSON content
    example  : "# Plan\n- Step 1"
    mandatory: false
  - name     : updatefreq
    desc     : Plan update frequency (auto, always, checkpoints, never)
    example  : "auto"
    mandatory: false
  - name     : updateinterval
    desc     : Number of steps between automatic plan updates when updatefreq=auto
    example  : "3"
    mandatory: false
  - name     : forceupdates
    desc     : Force plan updates even when actions fail
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : planlog
    desc     : Optional file path to append plan update logs
    example  : "plan-updates.log"
    mandatory: false
  - name     : outputfile
    desc     : Alternative key for outfile, used mainly during plan conversions
    example  : "/tmp/output.json"
    mandatory: false
  - name     : miniadocs
    desc     : Enable Mini-A docs shortcuts (alias for mini-a-docs)
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : extraskills
    desc     : Comma-separated list of additional skills roots for Mini Utils Tool
    example  : "/path/skillsA,/path/skillsB"
    mandatory: false
  - name     : secpass
    desc     : Password used to open OpenAF sBucket model secrets
    example  : "my-secret-passphrase"
    mandatory: false
  - name     : shellprefix
    desc     : Override shell prefix when converting plans or running commands from stored plans
    example  : "docker exec -it container sh -lc"
    mandatory: false
  - name     : format
    desc     : Output format for the final answer (md, json, yaml, toon or slon)
    example  : "json"
    mandatory: false
  - name     : auditch
    desc     : SLON/JSON definition of an audit channel to record agent activity
    example  : "(type: file, options: (file: '/tmp/mini-a-audit.log'))"
    mandatory: false
  - name     : toollog
    desc     : SLON/JSON definition of a channel that records every tool call, arguments and result
    example  : "(type: file, options: (file: '/tmp/mini-a-tools.log'))"
    mandatory: false
  - name     : metricsch
    desc     : SLON/JSON definition of an OpenAF channel where Mini-A metrics snapshots are recorded
    example  : "(name: 'mini-a-metrics', type: 'mvs', options: (file: '/tmp/mini-a-metrics.db'))"
    mandatory: false
  - name     : debugch
    desc     : SLON/JSON definition of a debug channel for LLM debugging (requires $llm.setDebugCh support)
    example  : "(type: file, options: (file: '/tmp/mini-a-llm-debug.log'))"
    mandatory: false
  - name     : debuglcch
    desc     : SLON/JSON definition of a debug channel for low-cost LLM debugging (requires $llm.setDebugCh support)
    example  : "(type: file, options: (file: '/tmp/mini-a-lc-llm-debug.log'))"
    mandatory: false
  - name     : debugvalch
    desc     : SLON/JSON definition of a debug channel for validation LLM debugging (requires $llm.setDebugCh support)
    example  : "(type: file, options: (file: '/tmp/mini-a-val-llm-debug.log'))"
    mandatory: false
  - name     : nosetmcpwd
    desc     : Do not set __flags.JSONRPC.cmd.defaultDir to mini-a oPack location
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : model
    desc     : Override the OAF_MODEL environment variable with a custom model configuration (string or JSON/SLON map)
    example  : "anthropic/claude-3-5-sonnet-20241022"
    mandatory: false
  - name     : modellc
    desc     : Override the low-cost model configuration used for summarization and tool selection (string or JSON/SLON map)
    example  : "anthropic/claude-3-5-haiku-20241022"
    mandatory: false
  - name     : modellock
    desc     : "Force Mini-A to always use a specific model tier, bypassing dynamic escalation. Values: \"main\", \"lc\", or \"auto\" (default)"
    example  : "lc"
    mandatory: false
    options  : ["main", "lc", "auto"]
  - name     : modelstrategy
    desc     : "Model strategy profile. Use \"default\" (existing behavior) or \"advisor\" (LC executor + main advisor consults)"
    example  : "advisor"
    mandatory: false
    options  : ["default", "advisor"]
  - name     : advisormaxuses
    desc     : Maximum number of advisor consultations per run when modelstrategy=advisor
    example  : "2"
    mandatory: false
  - name     : advisorenable
    desc     : Enable advisor consultations when modelstrategy=advisor
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : advisoronrisk
    desc     : Allow advisor consults on risk signals
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : advisoronambiguity
    desc     : Allow advisor consults on ambiguity signals
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : advisoronharddecision
    desc     : Allow advisor consults on hard-decision checkpoints
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : advisorcooldownsteps
    desc     : Minimum number of steps between advisor consultations when modelstrategy=advisor
    example  : "2"
    mandatory: false
  - name     : advisorbudgetratio
    desc     : Max advisor share of token budget (0-1) before low-value consults are declined
    example  : "0.20"
    mandatory: false
  - name     : emergencyreserve
    desc     : Reserve fraction inside advisor budget kept for high-value consults
    example  : "0.10"
    mandatory: false
  - name     : harddecision
    desc     : Hard-decision checkpoint mode (require, warn, off)
    example  : "warn"
    mandatory: false
    options  : ["require", "warn", "off"]
  - name     : evidencegate
    desc     : Enable lightweight evidence gate for non-trivial steps/final answers
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : evidencegatestrictness
    desc     : Evidence gate strictness (low, medium, high)
    example  : "medium"
    mandatory: false
    options  : ["low", "medium", "high"]
  - name     : lcescalatedefer
    desc     : When true (default), defer escalation by one step if the LC response confidence is >= 0.7
    example  : "true"
    mandatory: false
    options  : ["true", "false"]
  - name     : lcbudget
    desc     : Maximum total LC token usage before permanently switching to the main model for the session (0 = unlimited)
    example  : "50000"
    mandatory: false
  - name     : llmcomplexity
    desc     : When true, fire a quick LC model call to validate "medium" complexity heuristic results
    example  : "false"
    mandatory: false
    options  : ["true", "false"]
  - name     : saveplannotes
    desc     : Save execution notes back to the plan file after execution
    example  : "true"
    mandatory: false
    options  : ["true", "false"]

todo:
- MiniAgent

ojob:
  opacks      :
  - openaf: 20250725
  - mini-a
  catch       : printErrnl("[" + job.name + "] "); $err(exception, __, __, job.exec)
  #logToConsole: false   # to change when finished
  loadLibs    :
  - mini-a.js

jobs:
# -------------------------
- name : MiniAgent CheckEnv
  exec : | #js
    var hasModelOverride = isDef(args) && isDef(args.model) && ((isString(args.model) && args.model.trim().length > 0) || isMap(args.model))
    if (isUnDef(getEnv("OAF_MODEL")) && !hasModelOverride) {
      throw "OAF_MODEL environment variable not set. Please export OAF_MODEL or provide model= with your model configuration before running Mini-A."
    }

# ----------------
- name : MiniAgent
  from :
  - MiniAgent CheckEnv
  typeArgs:
    noLog   : false
    shortcut:
      name  : mini-a
      keyArg: goal
      args  :
        mcp            : mcp
        verbose        : verbose
        rpm            : rpm
        rtm            : rtm
        tpm            : tpm
        maxsteps       : maxsteps
        maxcontext     : maxcontext
        maxcontent     : maxcontent
        readwrite      : readwrite
        checkall       : checkall
        debug          : debug
        useshell       : useshell
        shell          : shell
        usesandbox     : usesandbox
        sandboxprofile : sandboxprofile
        extrahooks     : extrahooks
        knowledge      : knowledge
        youare         : youare
        chatyouare    : chatyouare
        outfile        : outfile
        outfileall     : outfileall
        outputfile     : outputfile
        libs           : libs
        model          : model
        modellc        : modellc
        modelval       : modelval
        conversation   : conversation
        format         : format
        raw            : raw
        showthinking   : showthinking
        shellallow     : shellallow
        shellbanextra  : shellbanextra
        shellallowpipes: shellallowpipes
        shellbatch     : shellbatch
        shellprefix    : shellprefix
        shelltimeout   : shelltimeout
        shellmaxbytes  : shellmaxbytes
        toolcachettl   : toolcachettl
        validationgoal : validationgoal
        valgoal        : valgoal
        deepresearch   : deepresearch
        maxcycles      : maxcycles
        validationthreshold: validationthreshold
        persistlearnings: persistlearnings
        usetools       : usetools
        usetoolslc     : usetoolslc
        usejsontool    : usejsontool
        useutils       : useutils
        useskills      : useskills
        usediagrams    : usediagrams
        usemermaid     : usemermaid
        usecharts      : usecharts
        useascii       : useascii
        usemaps        : usemaps
        usemath        : usemath
        usesvg         : usesvg
        usevectors     : usevectors
        usestream      : usestream
        mcpdynamic     : mcpdynamic
        mcpproxy       : mcpproxy
        mcpproxythreshold: mcpproxythreshold
        mcpproxytoon   : mcpproxytoon
        mcplazy        : mcplazy
        useplanning    : useplanning
        forceplanning  : forceplanning
        planstyle      : planstyle
        earlystopthreshold: earlystopthreshold
        planmode       : planmode
        validateplan   : validateplan
        convertplan    : convertplan
        resumefailed   : resumefailed
        chatbotmode    : chatbotmode
        promptprofile  : promptprofile
        systempromptbudget: systempromptbudget
        planfile       : planfile
        planformat     : planformat
        plancontent    : plancontent
        updatefreq     : updatefreq
        updateinterval : updateinterval
        forceupdates   : forceupdates
        planlog        : planlog
        rules          : rules
        state          : state
        usedelegation  : usedelegation
        workers        : workers
        workerreg      : workerreg
        workerregtoken : workerregtoken
        workerevictionttl: workerevictionttl
        maxconcurrent  : maxconcurrent
        delegationmaxdepth: delegationmaxdepth
        delegationtimeout: delegationtimeout
        delegationmaxretries: delegationmaxretries
        auditch        : auditch
        toollog        : toollog
        metricsch      : metricsch
        debugch        : debugch
        debuglcch      : debuglcch
        debugvalch     : debugvalch
        nosetmcpwd     : nosetmcpwd
        miniadocs      : miniadocs
        extraskills    : extraskills
        secpass        : secpass
        utilsroot      : utilsroot
        utilsallow     : utilsallow
        utilsdeny      : utilsdeny
        saveplannotes  : saveplannotes
        modellock      : modellock
        modelstrategy  : modelstrategy
        advisormaxuses : advisormaxuses
        advisorenable  : advisorenable
        advisoronrisk  : advisoronrisk
        advisoronambiguity: advisoronambiguity
        advisoronharddecision: advisoronharddecision
        advisorcooldownsteps: advisorcooldownsteps
        advisorbudgetratio: advisorbudgetratio
        emergencyreserve: emergencyreserve
        harddecision   : harddecision
        evidencegate   : evidencegate
        evidencegatestrictness: evidencegatestrictness
        lcescalatedefer: lcescalatedefer
        lcbudget       : lcbudget
        llmcomplexity  : llmcomplexity
  check:
    in:
      goal           : isString
      mcp            : default(__)
      verbose        : toBoolean.isBoolean.default(false)
      rpm            : toNumber.isNumber.default(__)
      rtm            : toNumber.isNumber.default(__)
      tpm            : toNumber.isNumber.default(__)
      maxsteps       : toNumber.isNumber.default(15)
      maxcontext     : toNumber.isNumber.default(0)
      compressgoal   : toBoolean.isBoolean.default(false)
      compressgoaltokens: toNumber.isNumber.default(250)
      compressgoalchars : toNumber.isNumber.default(1000)
      maxcontent     : toNumber.isNumber.default(__)
      readwrite      : toBoolean.isBoolean.default(__)
      checkall       : toBoolean.isBoolean.default(false)
      debug          : toBoolean.isBoolean.default(false)
      useshell       : toBoolean.isBoolean.default(__)
      shell          : isString.default(__)
      usesandbox     : isString.default(__)
      sandboxprofile : isString.default(__)
      extrahooks     : isString.default(__)
      knowledge      : isString.default(__)
      youare         : isString.default(__)
      chatyouare     : isString.default(__)
      outfile        : isString.default(__)
      outfileall     : isString.default(__)
      outputfile     : isString.default(__)
      libs           : isString.default(__)
      model          : default(__)
      modellc        : default(__)
      modelval       : default(__)
      conversation   : isString.default(__)
      format         : isString.default(__)
      raw            : toBoolean.isBoolean.default(false)
      showthinking   : toBoolean.isBoolean.default(false)
      shellallow     : isString.default(__)
      shellbanextra  : isString.default(__)
      shellallowpipes: toBoolean.isBoolean.default(false)
      shellbatch     : toBoolean.isBoolean.default(false)
      shellprefix    : isString.default(__)
      shelltimeout   : toNumber.isNumber.default(__)
      shellmaxbytes  : toNumber.isNumber.default(__)
      toolcachettl   : toNumber.isNumber.default(__)
      validationgoal : isString.default(__)
      valgoal        : isString.default(__)
      deepresearch   : toBoolean.isBoolean.default(false)
      maxcycles      : toNumber.isNumber.default(__)
      validationthreshold: isString.default(__)
      persistlearnings: toBoolean.isBoolean.default(__)
      usetools       : toBoolean.isBoolean.default(__)
      usetoolslc     : toBoolean.isBoolean.default(__)
      usejsontool    : toBoolean.isBoolean.default(__)
      useutils       : toBoolean.isBoolean.default(__)
      useskills      : toBoolean.isBoolean.default(false)
      usediagrams    : toBoolean.isBoolean.default(false)
      usemermaid     : toBoolean.isBoolean.default(false)
      usecharts      : toBoolean.isBoolean.default(false)
      useascii       : toBoolean.isBoolean.default(false)
      usemaps        : toBoolean.isBoolean.default(false)
      usemath        : toBoolean.isBoolean.default(false)
      usesvg         : toBoolean.isBoolean.default(false)
      usevectors     : toBoolean.isBoolean.default(false)
      usestream      : toBoolean.isBoolean.default(false)
      mcpdynamic     : toBoolean.isBoolean.default(false)
      mcpproxy       : toBoolean.isBoolean.default(__)
      mcpproxythreshold: toNumber.isNumber.default(__)
      mcpproxytoon   : toBoolean.isBoolean.default(false)
      mcplazy        : toBoolean.isBoolean.default(false)
      useplanning    : toBoolean.isBoolean.default(false)
      forceplanning  : toBoolean.isBoolean.default(false)
      planstyle      : isString.default(__)
      earlystopthreshold: toNumber.isNumber.default(__)
      planmode       : toBoolean.isBoolean.default(false)
      validateplan   : toBoolean.isBoolean.default(false)
      convertplan    : toBoolean.isBoolean.default(false)
      resumefailed   : toBoolean.isBoolean.default(false)
      chatbotmode    : toBoolean.isBoolean.default(false)
      promptprofile  : isString.default(__)
      systempromptbudget: toNumber.isNumber.default(__)
      planfile       : isString.default(__)
      planformat     : isString.default(__)
      plancontent    : isString.default(__)
      updatefreq     : isString.default(__)
      updateinterval : toNumber.isNumber.default(__)
      forceupdates   : toBoolean.isBoolean.default(false)
      planlog        : isString.default(__)
      rules          : default(__)
      state          : default(__)
      usedelegation  : toBoolean.isBoolean.default(false)
      workers        : isString.default(__)
      workerreg      : toNumber.isNumber.default(__)
      workerregtoken : isString.default(__)
      workerevictionttl: toNumber.isNumber.default(__)
      maxconcurrent  : toNumber.isNumber.default(__)
      delegationmaxdepth: toNumber.isNumber.default(__)
      delegationtimeout: toNumber.isNumber.default(__)
      delegationmaxretries: toNumber.isNumber.default(__)
      auditch        : default(__)
      toollog        : default(__)
      metricsch      : default(__)
      debugch        : default(__)
      debuglcch      : default(__)
      debugvalch     : default(__)
      nosetmcpwd     : toBoolean.isBoolean.default(false)
      miniadocs      : toBoolean.isBoolean.default(false)
      extraskills    : isString.default(__)
      secpass        : isString.default(__)
      utilsroot      : isString.default(__)
      utilsallow     : isString.default(__)
      utilsdeny      : isString.default(__)
      saveplannotes  : toBoolean.isBoolean.default(false)
      modellock      : isString.default(__)
      modelstrategy  : isString.default(__)
      advisormaxuses : toNumber.isNumber.default(__)
      advisorenable  : toBoolean.isBoolean.default(true)
      advisoronrisk  : toBoolean.isBoolean.default(true)
      advisoronambiguity: toBoolean.isBoolean.default(true)
      advisoronharddecision: toBoolean.isBoolean.default(true)
      advisorcooldownsteps: toNumber.isNumber.default(__)
      advisorbudgetratio: toNumber.isNumber.default(0.20)
      emergencyreserve: toNumber.isNumber.default(0.10)
      harddecision   : isString.default("warn")
      evidencegate   : toBoolean.isBoolean.default(false)
      evidencegatestrictness: isString.default("medium")
      lcescalatedefer: toBoolean.isBoolean.default(true)
      lcbudget       : toNumber.isNumber.default(0)
      llmcomplexity  : toBoolean.isBoolean.default(false)
  exec : | #js
    log(`🎯 goal: ${args.goal}`)
    MiniA.applyLibEnvDefault(args)
    var _ma = new MiniA()
    function warnOnUnknownParameters() {
      if (!isMap(args)) return
      if (!MiniA.shouldWarnUnknownArgs(args)) return
      MiniA.warnUnknownArgs(args, {
        extraIgnoredArgs: {
          "mini-a"                : true,
          exec                    : true,
          agent                   : true,
          init                    : true,
          "__id"                  : true,
          objid                   : true,
          execid                  : true,
          "__format"              : true,
          "__interaction_source"  : true,
          "__explicitargkeys"     : true,
          "__modeapplied"         : true,
          "__unknownargsreported" : true
        },
        logger: function(message) { logWarn(message) }
      })
    }
    warnOnUnknownParameters()
    function parseHookBoolean(value) {
      if (isUnDef(value) || value === null) return false
      var lowered = ("" + value).trim().toLowerCase()
      return lowered === "true" || lowered === "1" || lowered === "yes" || lowered === "y" || lowered === "on"
    }
    function canonicalizeHookPath(path) {
      if (!isString(path) || path.trim().length === 0) return path
      try {
        return io.fileInfo(path).canonicalPath
      } catch (e) {
        return path
      }
    }
    function loadHooksFromDir(dirPath, hooks) {
      var validEvents = ["before_goal", "after_goal", "before_tool", "after_tool", "before_shell", "after_shell"]
      try {
        if (!io.fileExists(dirPath)) return
        var info = io.fileInfo(dirPath)
        if (!isObject(info) || info.isDirectory !== true) return
        var listing = io.listFiles(dirPath)
        if (!isObject(listing) || !isArray(listing.files)) return
        listing.files.forEach(function(file) {
          if (!isObject(file) || file.isDirectory === true) return
          if (!isString(file.filename) || file.filename.length === 0) return
          if (!/\.(yaml|yml|json)$/i.test(file.filename)) return
          var fullPath = canonicalizeHookPath(dirPath + "/" + file.filename)
          try {
            var hookDef = /\.json$/i.test(file.filename) ? io.readFileJSON(fullPath) : io.readFileYAML(fullPath)
            if (!isObject(hookDef)) return
            var event = isString(hookDef.event) ? hookDef.event.trim().toLowerCase() : ""
            if (validEvents.indexOf(event) < 0) return
            var cmd = isString(hookDef.command) ? hookDef.command.trim() : ""
            if (cmd.length === 0) return
            var toolFilter = []
            if (isString(hookDef.toolFilter) && hookDef.toolFilter.trim().length > 0) {
              toolFilter = hookDef.toolFilter.split(",").map(function(s) { return s.trim().toLowerCase() }).filter(function(s) { return s.length > 0 })
            }
            hooks[event].push({
              name        : file.filename.replace(/\.(yaml|yml|json)$/i, ""),
              command     : cmd,
              toolFilter  : toolFilter,
              injectOutput: parseHookBoolean(hookDef.injectOutput) === true,
              timeout     : (isNumber(hookDef.timeout) && hookDef.timeout > 0) ? hookDef.timeout : 5000,
              failBlocks  : parseHookBoolean(hookDef.failBlocks) === true,
              env         : isObject(hookDef.env) ? hookDef.env : {}
            })
          } catch (hookParseError) {
            logWarn("Failed to parse hook file '" + file.filename + "': " + hookParseError)
          }
        })
      } catch (hookLoadError) {
        logWarn("Failed to load hooks from '" + dirPath + "': " + hookLoadError)
      }
    }
    function loadHooks() {
      var validEvents = ["before_goal", "after_goal", "before_tool", "after_tool", "before_shell", "after_shell"]
      var hooks = {}
      validEvents.forEach(function(ev) { hooks[ev] = [] })
      var historyHome = isDef(__gHDir) ? __gHDir() : java.lang.System.getProperty("user.home")
      var hooksDirPath = canonicalizeHookPath(historyHome + "/.openaf-mini-a/hooks")
      loadHooksFromDir(hooksDirPath, hooks)
      if (isString(args.extrahooks) && args.extrahooks.trim().length > 0) {
        args.extrahooks.split(",").map(function(s) { return s.trim() }).filter(function(s) { return s.length > 0 }).forEach(function(dir) {
          loadHooksFromDir(canonicalizeHookPath(dir), hooks)
        })
      }
      return hooks
    }
    var loadedHooks = loadHooks()
    function runHooks(event, contextVars) {
      var hooksForEvent = isArray(loadedHooks[event]) ? loadedHooks[event] : []
      if (hooksForEvent.length === 0) return { outputs: [], blocked: false }
      var outputs = []
      var blocked = false
      var vars = isObject(contextVars) ? contextVars : {}
      hooksForEvent.forEach(function(hook) {
        if (hook.toolFilter.length > 0 && isString(vars.MINI_A_TOOL)) {
          var toolLower = vars.MINI_A_TOOL.toLowerCase()
          if (hook.toolFilter.indexOf(toolLower) < 0) return
        }
        try {
          var env = {}
          Object.keys(hook.env).forEach(function(k) { env[k] = String(hook.env[k]) })
          Object.keys(vars).forEach(function(k) { env[k] = String(vars[k]) })
          env.MINI_A_HOOK_NAME = hook.name
          env.MINI_A_HOOK_EVENT = event
          var result = $sh(hook.command).timeout(hook.timeout).envs(env).get(0)
          var stdout = isString(result.stdout) ? result.stdout.trim() : ""
          var stderr = isString(result.stderr) ? result.stderr.trim() : ""
          var exitCode = isNumber(result.exitcode) ? result.exitcode : -1
          if (exitCode !== 0) {
            logWarn("Hook '" + hook.name + "' (" + event + ") exited with code " + exitCode + (stderr.length > 0 ? ": " + stderr.substring(0, 200) : ""))
            if (hook.failBlocks) blocked = true
          }
          if (hook.injectOutput && stdout.length > 0) outputs.push({ hookName: hook.name, output: stdout.substring(0, 4096) })
        } catch (hookExecError) {
          logWarn("Hook '" + hook.name + "' (" + event + ") failed: " + hookExecError)
          if (hook.failBlocks) blocked = true
        }
      })
      return { outputs: outputs, blocked: blocked }
    }
    if (isDef(args.usemermaid) && isUnDef(args.usediagrams)) args.usediagrams = args.usemermaid
    if (args.usevectors === true) {
      if (isUnDef(args.usesvg) || !args.usesvg) args.usesvg = true
      if (isUnDef(args.usediagrams) || !args.usediagrams) args.usediagrams = true
    }
    if (args.usesvg === true && isUnDef(args.browsercontext)) args.browsercontext = true
    if (isDef(args.valgoal) && isUnDef(args.validationgoal)) args.validationgoal = args.valgoal
    if (isDef(args.rtm) && isUnDef(args.rpm)) args.rpm = args.rtm
    if (isDef(args.maxcontent) && isUnDef(args.maxcontext)) args.maxcontext = args.maxcontent
    if (isUnDef(args.format)) args.format = "md"
    if (isUnDef(args.__format) && isDef(args.format)) args.__format = args.format
    var originalGoalText = isString(args.goal) ? args.goal : ""
    var beforeGoalResult = runHooks("before_goal", { MINI_A_GOAL: originalGoalText })
    if (beforeGoalResult.blocked) {
      logWarn("Goal blocked by a before_goal hook.")
      return
    }
    if (isArray(beforeGoalResult.outputs) && beforeGoalResult.outputs.length > 0) {
      var hookPrefix = beforeGoalResult.outputs.map(function(o) { return "[Hook " + o.hookName + "] " + o.output }).join("\n")
      if (isString(args.hookcontext) && args.hookcontext.length > 0) {
        args.hookcontext = args.hookcontext + "\n" + hookPrefix
      } else {
        args.hookcontext = hookPrefix
      }
    }
    if (isFunction(_ma.setHookFn)) {
      _ma.setHookFn(function(event, contextVars) {
        return runHooks(event, contextVars)
      })
    }
    var _r = __
    try {
      _ma.init(args)
      _r = _ma.start(args)
      var resultPreview = isString(_r) ? _r.substring(0, 2000) : (isDef(_r) ? stringify(_r, __, "").substring(0, 2000) : "")
      runHooks("after_goal", { MINI_A_GOAL: originalGoalText, MINI_A_RESULT: resultPreview })
      if (isUnDef(args.outfile)) {
        if (isObject(_r)) 
          ow.oJob.output(_r, args)
        else
          print(_r)
      }
    } finally {
      try {
        if (isFunction(_ma._stopAgentResources)) _ma._stopAgentResources()
      } catch(ignoreAgentStop) {}
    }