Merge pull request #122 from OpenAF/codex/create-mcp-server-for-ollama-api

Codex-generated pull request

Author: nmaguiar

CHEATSHEET.md

@@ -546,7 +546,7 @@ mini-a mode=chatbot goal="help me plan a trip"
 # Use web mode
 ./mini-a-web.sh mode=web onport=8888
 
-# Custom preset (in ~/.openaf-mini-a_modes.yaml)
+# Custom preset (in ~/.openaf-mini-a/modes.yaml)
 modes:
   mypreset:
     useshell: true

README.md

@@ -344,7 +344,7 @@ The tester includes automatic cleanup with shutdown handlers to properly close M
   - **Autonomous Delegation** - LLM decides when to delegate via `delegate-subtask` tool
   - **Manual Delegation** - Console commands for interactive control (`/delegate`, `/subtasks`, `/subtask`)
   - **Depth Tracking** - Configurable nesting limits with automatic retry and deadline enforcement
-- **Conversation Persistence** - Save and resume conversations across sessions (`conversation=...`; in `mini-a-con`, use `resume=true` to continue the latest thread)
+- **Conversation Persistence** - Save and resume conversations across sessions (`conversation=...`; in `mini-a-con`, combine `usehistory=true`, `historykeep=true`, and `resume=true` to pick and continue prior console threads stored under `~/.openaf-mini-a/history/`; use `historykeepperiod=` and/or `historykeepcount=` for retention)
 - **Rate Limiting** - Built-in rate limiting for API usage control
 - **Metrics & Observability** - Comprehensive runtime metrics for monitoring and cost tracking
 - **ASCII Sketch Guidance** - Encourage text-based sketch outputs in responses (`useascii=true`)
@@ -386,7 +386,7 @@ Mini-A ships with complementary components:
 - **`mini-a-subtask.js`** - SubtaskManager for local child-agent delegation and remote worker delegation
 - **`mini-a-web.sh` / `mini-a-web.yaml`** - Lightweight HTTP server for browser UI
 - **`mini-a-worker.yaml`** - Headless HTTP API server for programmatic agent delegation (launch with `mini-a workermode=true`)
-- **`mini-a-modes.yaml`** - Built-in configuration presets for common use cases (can be extended with `~/.openaf-mini-a_modes.yaml`)
+- **`mini-a-modes.yaml`** - Built-in configuration presets for common use cases (can be extended with `~/.openaf-mini-a_modes.yaml` or `~/.openaf-mini-a/modes.yaml`)
 - **`public/`** - Browser interface assets
 
 ## Common Configuration Options
@@ -422,7 +422,7 @@ Mini-A ships with complementary components:
 | `usemaps` | Encourage Leaflet-based interactive map outputs for geographic data | `false` |
 | `usemath` | Encourage LaTeX-style math formulas (`$...$`, `$$...$$`) for KaTeX rendering in the web UI | `false` |
 | `usestream` | Enable real-time token streaming as LLM generates responses | `false` |
-| `mode` | Apply preset from `mini-a-modes.yaml` or `~/.openaf-mini-a_modes.yaml` | - |
+| `mode` | Apply preset from `mini-a-modes.yaml`, `~/.openaf-mini-a_modes.yaml`, or `~/.openaf-mini-a/modes.yaml` | - |
 | `modelman` | Launch the interactive model definitions manager | `false` |
 | `workermode` | Launch the Worker API server (`mini-a-worker.yaml`) from the console entrypoint | `false` |
 | `workers` | Comma-separated list of worker URLs for remote delegation (`workers=http://host1:8080,http://host2:8080`) | - |

USAGE.md

@@ -324,7 +324,7 @@ oJob wrappers (for example `ojob mini-a.yaml modelman=true`).
 
 ## Mode Presets
 
-Mini-A ships with reusable argument bundles so you can switch behaviors without remembering every flag. Pass `mode=<name>` with `opack exec mini-a`, `mini-a`, `mini-a.sh`, `mini-a.yaml`, or `mini-a-main.yaml` and the runtime will merge the corresponding preset from [`mini-a-modes.yaml`](mini-a-modes.yaml) and optionally from `~/.openaf-mini-a_modes.yaml` (custom modes override built-in ones) before applying any explicit flags you provide on the command line.
+Mini-A ships with reusable argument bundles so you can switch behaviors without remembering every flag. Pass `mode=<name>` with `opack exec mini-a`, `mini-a`, `mini-a.sh`, `mini-a.yaml`, or `mini-a-main.yaml` and the runtime will merge the corresponding preset from [`mini-a-modes.yaml`](mini-a-modes.yaml) and optionally from `~/.openaf-mini-a_modes.yaml` and `~/.openaf-mini-a/modes.yaml` (custom modes override built-in ones, and `~/.openaf-mini-a/modes.yaml` overrides the legacy file when both exist) before applying any explicit flags you provide on the command line.
 
 Set `OAF_MINI_A_MODE=<name>` to pick a default preset when you do not supply `mode=` on the command line (helpful when using the `mini-a` alias). Explicit `mode=` arguments continue to take precedence over the environment variable.
 
@@ -340,12 +340,12 @@ Set `OAF_MINI_A_MODE=<name>` to pick a default preset when you do not supply `mo
 
 ### Creating Custom Presets
 
-Create your own presets by creating a `~/.openaf-mini-a_modes.yaml` file in your home directory. Custom modes are automatically merged with the built-in presets from `mini-a-modes.yaml`, with custom definitions taking precedence. The agent loads both YAML files on each run, so custom additions and overrides are immediately available.
+Create your own presets by creating either a `~/.openaf-mini-a_modes.yaml` file or a `~/.openaf-mini-a/modes.yaml` file in your home directory. Custom modes are automatically merged with the built-in presets from `mini-a-modes.yaml`, with custom definitions taking precedence. If both custom files exist, `~/.openaf-mini-a/modes.yaml` overrides the legacy file. The agent loads these YAML files on each run, so custom additions and overrides are immediately available.
 
 **Example custom preset:**
 
 ```yaml
-# In ~/.openaf-mini-a_modes.yaml
+# In ~/.openaf-mini-a/modes.yaml
 modes:
   mypreset:
     useshell: true
@@ -766,7 +766,7 @@ The `start()` method accepts various configuration options:
 - **`showthinking`** (boolean, default: false): Use raw prompt calls to surface XML-tagged thinking blocks (for example `<thinking>...</thinking>`) as thought logs
 - **`chatbotmode`** (boolean, default: false): Replace the agent workflow with a lightweight conversational assistant prompt
 - **`useplanning`** (boolean, default: false): Load (or maintain) a persistent task plan in agent mode. When no pre-generated plan is available Mini-A falls back to the adaptive in-session planner and disables the feature for trivial goals.
-- **`mode`** (string): Apply a preset from [`mini-a-modes.yaml`](mini-a-modes.yaml) or `~/.openaf-mini-a_modes.yaml` to prefill a bundle of related flags
+- **`mode`** (string): Apply a preset from [`mini-a-modes.yaml`](mini-a-modes.yaml), `~/.openaf-mini-a_modes.yaml`, or `~/.openaf-mini-a/modes.yaml` to prefill a bundle of related flags
 
 #### Dual-Model Controls
 - **`modellc`** (string): Override the low-cost model configuration at runtime (same format as `OAF_LC_MODEL`). Useful for quick per-run model selection without changing environment variables.
@@ -925,11 +925,16 @@ Only when every stage returns an empty list (or errors) does Mini-A log the issu
 
 #### Conversation Management
 - **`conversation`** (string): Path to file for loading/saving conversation history
-- **`resume`** (boolean, default: false, `mini-a-con`): Reuse the last conversation and restore the most recent goal/result context when running from the interactive console (`mini-a` / `opack exec mini-a`)
+- **`resume`** (boolean, default: false, `mini-a-con`): Resume a previous console conversation. When `conversation` is omitted and `usehistory=true`, the console lists `~/.openaf-mini-a/history/*.json` and lets you choose which thread to continue.
+- **`usehistory`** (boolean, default: false, `mini-a-con`): Enable console history discovery from `~/.openaf-mini-a/history/`.
+- **`historykeep`** (boolean, default: false, `mini-a-con`): Store console conversation files in `~/.openaf-mini-a/history/` using `conversation-yyyyMMdd-HHmmss.json` style names.
+- **`historykeepperiod`** (number, `mini-a-con`): Automatically delete kept conversation files older than the provided number of minutes.
+- **`historykeepcount`** (number, `mini-a-con`): Automatically delete kept conversation files beyond the newest N entries.
+  - When both `historykeepperiod` and `historykeepcount` are set, either rule can prune a saved conversation file.
 - **`state`** (object|string): Initial structured state (JSON/SLON) injected before the first step and persisted across turns
 
 #### Mode Presets
-- **`mode`** (string): Shortcut for loading a preset argument bundle from [`mini-a-modes.yaml`](mini-a-modes.yaml) or `~/.openaf-mini-a_modes.yaml` (custom modes override built-in ones). Presets are merged before explicit flags, so command-line overrides always win. Bundled configurations include:
+- **`mode`** (string): Shortcut for loading a preset argument bundle from [`mini-a-modes.yaml`](mini-a-modes.yaml), `~/.openaf-mini-a_modes.yaml`, or `~/.openaf-mini-a/modes.yaml` (custom modes override built-in ones, and the new path overrides the legacy one when both exist). Presets are merged before explicit flags, so command-line overrides always win. Bundled configurations include:
   - `shell` – Enables read-only shell access.
   - `shellrw` – Enables shell access with write permissions (`readwrite=true`).
   - `shellutils` – Adds the Mini File Tool helpers as an MCP (`useutils=true mini-a-docs=true usetools=true`) exposing `init`, `filesystemQuery`, `filesystemModify`, and `markdownFiles` actions.
@@ -2259,6 +2264,14 @@ Resume the last conversation directly from the interactive console:
 mini-a conversation=chat-history.json resume=true
 ```
 
+Or keep console sessions in the default history folder and choose one interactively when resuming:
+
+```bash
+mini-a usehistory=true historykeep=true resume=true
+```
+
+Console history payloads now keep both `created_at` and `updated_at` timestamps in addition to the conversation entries, which makes retention and manual inspection easier.
+
 ### Context Management
 
 ```javascript
@@ -2427,6 +2440,7 @@ This will show:
 Mini-A records extensive counters that help track behaviour and costs:
 
 - Call `agent.getMetrics()` to obtain a snapshot grouped by LLM usage, outcomes, shell approvals/denials, context management, and summarization activity.
+- Console history flows also update `history` metrics so you can track started/resumed sessions plus kept/deleted conversation files when using `mini-a-con`, including separate counters for age-based and count-based pruning.
 - OpenAF automatically registers these counters under the `mini-a` namespace via `ow.metrics.add('mini-a', ...)`, so collectors that understand OpenAF metrics can scrape them.
 - Metrics are updated live as the agent progresses, making them ideal for dashboards or alerting when an agent gets stuck.
 
@@ -2447,6 +2461,7 @@ Mini-A records extensive counters that help track behaviour and costs:
 | `tool_cache` | `hits`, `misses`, `total_requests`, `hit_rate` | Tool result caching metrics for deterministic and read-only MCP tools. Tracks cache effectiveness and provides hit rate percentage. |
 | `mcp_resilience` | `circuit_breaker_trips`, `circuit_breaker_resets`, `lazy_init_success`, `lazy_init_failed` | MCP resilience and optimization metrics. Circuit breaker trips/resets track connection health management. Lazy initialization metrics show deferred MCP connection establishment when `mcplazy=true`. |
 | `delegation` | `total`, `running`, `completed`, `failed`, `cancelled`, `timedout`, `retried`, `workers_total`, `workers_static`, `workers_dynamic`, `workers_healthy`, `avgDurationMs`, `maxDepthUsed` | Subtask delegation metrics (when `usedelegation=true`). Tracks child agent lifecycle, retries, worker pool composition/health, average duration, and deepest nesting level reached. |
+| `history` | `sessions_started`, `sessions_resumed`, `files_kept`, `files_deleted`, `files_deleted_by_period`, `files_deleted_by_count` | Console conversation history metrics. Tracks new vs resumed console sessions, how many history files were kept, and how many were pruned overall, by age rule, or by count rule. |
 
 These counters mirror what is exported via `ow.metrics.add('mini-a', ...)`, so the same structure appears in Prometheus/Grafana when scraped through OpenAF.
 

mcps/README.md

@@ -25,6 +25,7 @@
 | mcp-s3     | S3 object storage MCP           | STDIO/HTTP       | (included) | [mcp-s3.yaml](mcp-s3.yaml)         |
 | mcp-telco  | Telecommunications utilities MCP (country codes, phone number info) | STDIO/HTTP | (included) | [mcp-telco.yaml](mcp-telco.yaml)   |
 | mcp-weather | Weather information MCP (wttr.in)         | STDIO/HTTP | (included) | [mcp-weather.yaml](mcp-weather.yaml) |
+| mcp-ollama-web-search | Ollama web search API MCP      | STDIO/HTTP       | (included) | [mcp-ollama-web-search.yaml](mcp-ollama-web-search.yaml) |
 | mcp-web    | Web search and URL fetching MCP | STDIO/HTTP       | (included) | [mcp-web.yaml](mcp-web.yaml)       |
 | mcp-math   | Mathematical operations and unit conversions | STDIO/HTTP | (included) | [mcp-math.yaml](mcp-math.yaml)     |
 

mcps/mcp-mini-a.yaml

@@ -243,25 +243,29 @@ jobs:
 
       // Load custom modes from user's home directory
       var modesHome = isDef(__gHDir) ? __gHDir() : java.lang.System.getProperty("user.home")
-      var customModesPath = resolveCanonicalPath(modesHome, ".openaf-mini-a_modes.yaml")
-      if (io.fileExists(customModesPath)) {
-        try {
-          var customLoaded = io.readFileYAML(customModesPath)
-          var customPresets = {}
-          if (isMap(customLoaded) && isMap(customLoaded.modes)) {
-            customPresets = customLoaded.modes
-          } else if (isMap(customLoaded)) {
-            customPresets = customLoaded
+      ;[
+        resolveCanonicalPath(modesHome, ".openaf-mini-a_modes.yaml"),
+        resolveCanonicalPath(modesHome, ".openaf-mini-a/modes.yaml")
+      ].forEach(function(customModesPath) {
+        if (io.fileExists(customModesPath)) {
+          try {
+            var customLoaded = io.readFileYAML(customModesPath)
+            var customPresets = {}
+            if (isMap(customLoaded) && isMap(customLoaded.modes)) {
+              customPresets = customLoaded.modes
+            } else if (isMap(customLoaded)) {
+              customPresets = customLoaded
+            }
+            // Merge custom modes with default modes (later custom files override earlier ones)
+            if (isMap(customPresets) && Object.keys(customPresets).length > 0) {
+              presets = merge(presets, customPresets)
+            }
+          } catch(e) {
+            var errMsg = (isDef(e) && isString(e.message)) ? e.message : e
+            logWarn("Failed to load custom mode presets from '" + customModesPath + "': " + errMsg)
           }
-          // Merge custom modes with default modes (custom overrides defaults)
-          if (isMap(customPresets) && Object.keys(customPresets).length > 0) {
-            presets = merge(presets, customPresets)
-          }
-        } catch(e) {
-          var errMsg = (isDef(e) && isString(e.message)) ? e.message : e
-          logWarn("Failed to load custom mode presets from '" + customModesPath + "': " + errMsg)
         }
-      }
+      })
 
       if (!isMap(presets) || isUnDef(presets[modeName])) {
         logWarn("Mode '" + modeName + "' requested but not found in presets.")

mcps/mcp-ollama-web-search.yaml

@@ -0,0 +1,110 @@
+# Author: OpenAI Assistant
+help:
+  text   : A STDIO/HTTP MCP server for the Ollama web search API
+  expects:
+  - name     : apiKey
+    desc     : Ollama API key (can also be provided via OLLAMA_API_KEY env var)
+    mandatory: true
+  - name     : baseUrl
+    desc     : Ollama API base URL
+    example  : "https://ollama.com"
+    mandatory: false
+  - name     : onport
+    desc     : If defined starts an HTTP MCP server on this port; otherwise uses STDIO
+    example  : "8888"
+    mandatory: false
+
+
+todo:
+- Init
+- (if    ): "isDef(args.onport)"
+  ((then)):
+  - (httpdStart   ): "${onport:-8080}"
+  - (httpdHealthz ): "${onport:-8080}"
+  - (httpdMetrics ): "${onport:-8080}"
+  - (httpdMCP     ): "${onport:-8080}"
+    ((description)): &MCPSERVER
+      serverInfo:
+        name   : mini-a-ollama-web-search
+        title  : OpenAF mini-a MCP Ollama web search server
+        version: 1.0.0
+
+    ((fnsMeta)): &MCPFNSMETA
+      web-search:
+        name       : web-search
+        description: Search the web through Ollama's web_search API endpoint.
+        inputSchema:
+          type      : object
+          properties:
+            query:
+              type       : string
+              description: Search query to send to Ollama.
+            options:
+              type       : object
+              description: Optional extra API payload fields forwarded as-is.
+          required: [ query ]
+        annotations:
+          title         : web-search
+          readOnlyHint  : true
+          idempotentHint: true
+
+    ((fns    )): &MCPFNS
+      web-search: Ollama web search
+
+  ((else)):
+  - (stdioMCP ): *MCPSERVER
+    ((fnsMeta)): *MCPFNSMETA
+    ((fns    )): *MCPFNS
+
+ojob:
+  opacks      :
+  - openaf     : 20250915
+  - oJob-common: 20250914
+  catch       : printErrnl("[" + job.name + "] "); $err(exception, __, __, job.exec)
+  logToConsole: false
+  argsFromEnvs: true
+  daemon      : true
+  unique      :
+    pidFile     : .mcp-ollama-web-search.pid
+    killPrevious: true
+
+include:
+- oJobMCP.yaml
+
+jobs:
+# -----------
+- name : Init
+  check:
+    in:
+      apiKey : isString.default(__)
+      baseUrl: isString.default("https://ollama.com")
+  exec : | #js
+    if (isUnDef(global.__ollamaWebSearchConfig)) {
+      if (isUnDef(args.apiKey) && isDef(__envs.OLLAMA_API_KEY)) args.apiKey = __envs.OLLAMA_API_KEY
+      _$(args.apiKey, "apiKey").isString().$_()
+
+      global.__ollamaWebSearchConfig = {
+        baseUrl: String(args.baseUrl).replace(/\/$/, ""),
+        apiKey : args.apiKey
+      }
+    }
+
+# ------------------------
+- name : Ollama web search
+  from : Init
+  check:
+    in:
+      query  : isString
+      options: isMap.default({})
+  exec : | #js
+    var payload = merge({ query: args.query }, args.options)
+    var cfg = global.__ollamaWebSearchConfig
+
+    var rest = $rest({
+      requestHeaders: {
+        "Authorization": "Bearer " + cfg.apiKey,
+        "Content-Type" : "application/json"
+      }
+    })
+
+    return rest.post(cfg.baseUrl + "/api/web_search", payload)