The registry handler hardcoded mode=args.get("mode", "summary") and the
function signature defaulted to "summary", which together made the
tools.session_search.default_mode config knob structurally unreachable
from real tool calls — _resolve_user_default_mode() only fires when
mode is None/empty, but neither path ever delivered None.
Drop both "summary" fallbacks so an omitted mode flows through as None
and the config-resolution branch can run.
Adds two tests: a static guard on the registry handler source pattern
(mirroring the existing run_agent.py one) and an end-to-end regression
that dispatches through the registry with default_mode='fast' configured
and asserts result["mode"] == "fast".
Summary mode invokes an auxiliary LLM (same Opus-tier model in default
'auto' routing) once per session summarised, with up to ~28K input
tokens (MAX_SESSION_CHARS=100K chars) and up to 10K output tokens
(MAX_SUMMARY_TOKENS) per call. That cost was being silently discarded:
_summarize_session() consumed response.usage only for the content string
and threw the usage data away. Smoke-test cost reporting showed
summary-mode scenarios at a fraction of their real spend because of it.
This patch:
- Changes _summarize_session() to return (content, usage) where usage
is a normalised dict {model, input_tokens, output_tokens,
cache_read_tokens, cache_creation_tokens} or None when the provider
didn't surface usage.
- Adds _extract_aux_usage() that handles both OpenAI-style
(prompt_tokens/completion_tokens, prompt_tokens_details.cached_tokens)
and Anthropic-style (input_tokens/output_tokens,
cache_read_input_tokens, cache_creation_input_tokens) usage shapes.
- The summary-mode caller aggregates per-session usage into both an
entry-level 'aux_usage' field and a top-level 'aux_usage_total'
carrying a call_count. The aggregate is omitted from the payload
entirely when no usage data was captured (test mocks, providers that
don't report it) so consumers can distinguish 'no data' from
'all zero'.
Note: this surfaces aux cost in the tool RESPONSE, where downstream
metrics extraction can pick it up. It does NOT yet attribute the cost
back to the parent session row (sessions.input_tokens / output_tokens /
estimated_cost_usd) — that's a wider fix to async_call_llm and the
session DB, out of scope here. Aggregator scripts (smoke-test
extractor, dashboards) get the data they need from the tool payload
without that wider change.
Two schema description tweaks driven by smoke-test findings (PLAN.md v1.8):
1. S09 (search-fidelity FAIL) — agent skipped session_search entirely
when asked 'what's the status of the commons-messaging PR on
yoniebans.github.io?' and went straight to gh pr list. Technically
correct that no PR existed, but missed two prior sessions and today's
planning doc that referenced the branch.
Fix: lead the USE THIS PROACTIVELY list with an explicit instruction
to call session_search BEFORE external tools (gh, GitHub API, web,
file inspection) when the question references prior work. The session
DB carries what was DISCUSSED and DECIDED; external tools only show
current world state. Use session_search to find context, external
tools to verify reality.
2. S08 (schema-teaching weak case) — agent was asked to drill cold with
multi-anchor guided. Did NOT refuse. Improvised recent → fast → fast
→ guided in one turn. Functionally correct (self-fed anchors from its
own preceding fast calls), but the schema's 'cannot be a starting
move' framing was followed in spirit, not articulated. The agent
should EITHER refuse and ask, OR explicitly call fast first as a
prerequisite — not silently improvise.
Fix: reword 'Cannot be a starting move on its own' to a directive
'REQUIRES anchors from a prior fast or summary call. If you have no
prior fast hit, call fast FIRST and use its match_message_id values
as anchors. Never invent anchors or guess session_ids.' Same change
echoed in the per-parameter mode description for the second-read
reinforcement.
Other 12 scenarios were clean. Schema base is good; these are surgical
fixes for the two cases where the framing didn't land hard enough.
93/93 session_search + get_messages_around tests still pass.
Live-test conversation surfaced that the 'three modes (fast, summary,
guided)' framing makes the modes sound like peers when they aren't.
Guided literally cannot be a default — _resolve_user_default_mode()
already rejects it and forces summary. The honest shape is two
starting moves (fast, summary) plus one follow-up move (guided) that
needs anchors from a prior call.
Two cleanups follow from that:
1) Schema description rewritten with the 'two starts + one follow-up'
framing. Old MODES 1/2/3 list replaced with a structured 'Starting
moves' / 'Follow-up move' block. Recommended flows section folded
in (the per-question heuristics are now under each move's bullet).
2) Single-anchor schema parameters (session_id, around_message_id)
REMOVED from the LLM-facing schema. After multi-anchor shipped,
one-element anchors=[{...}] handles the single-anchor case
identically. Keeping both shapes in the schema was confusing — the
LLM occasionally tried to pair them or asked which to use.
The Python session_search() function still accepts session_id /
around_message_id kwargs for direct callers and test fixtures
(back-compat); only the LLM-facing schema lost them. Parameter
surface dropped from 6 LLM-visible knobs to 4 (query, role_filter,
limit, mode + anchors, window).
The mode parameter's description also got tightened — short summary of
each mode, points to the top-level description for when-to-use
guidance. The old description was duplicating the top-level mode
explanation in a more verbose form.
Updated test_schema_advertises_guided_mode:
- Asserts match_message_id pairing guidance now lives on the
anchors parameter, not the top-level description.
- Explicitly asserts session_id / around_message_id are NOT in the
schema (regression-proof against re-adding them).
93/93 session_search + get_messages_around tests passing.
This is the param-surface cleanup discussed yesterday alongside the
default_mode config commit. Closes the schema-surface side of the
'fast vs guided is confusing' user feedback; the spike doc §6.7 / §7
get matching updates in a separate commit on the architecture branch.
The default mode is normally 'summary' (LLM recap of matched sessions).
This commit lets a user override that via:
# ~/.hermes/config.yaml
tools:
session_search:
default_mode: fast
Useful for power users who want to live with fast-as-default for a few
days and see how it feels — without having to pass mode='fast' on every
call. The summary path is still one explicit kwarg away.
Resolution order at call time:
1. Explicit mode= argument from the LLM (always wins)
2. tools.session_search.default_mode in ~/.hermes/config.yaml
3. 'summary' (final fallback)
Implementation:
- New helper _resolve_user_default_mode() in tools/session_search_tool.py
reads the value via hermes_cli.config.load_config(). Wrapped in
functools.lru_cache so the YAML read happens at most once per process
(config changes need a CLI / TUI restart, which is the existing
convention).
- Validates: must be a string, must be 'fast' or 'summary'. Anything
else (including 'guided', which needs anchors and can't stand alone)
logs a warning and falls back to 'summary'. The user gets feedback
when they typo their config.
- session_search()'s mode normaliser checks for None/empty/non-string
first and resolves the user default before applying alias mapping.
Explicit modes still take precedence over config.
- Both dispatch sites in run_agent.py changed from
mode=function_args.get('mode', 'summary') → mode=function_args.get('mode').
Hardcoding 'summary' at dispatch would shadow the new config-default
layer. Added a guard assert in test_run_agent_special_session_search_paths_forward_mode
so a regression to the old shape fails loudly.
- Schema description gets one extra sentence acknowledging the
user-configurable default so the LLM's own description of the tool
reflects reality.
Tests (+8):
- test_unset_mode_falls_back_to_summary_when_config_missing
- test_user_can_configure_fast_as_default
- test_user_can_configure_summary_as_default_explicitly
- test_invalid_default_mode_warns_and_falls_back (typo test)
- test_guided_as_default_mode_is_rejected
- test_non_string_default_mode_falls_back (bogus YAML types)
- test_explicit_mode_argument_overrides_user_default
- test_unset_mode_with_config_default_fast_runs_fast_path (e2e)
93/93 session_search + get_messages_around tests passing.
This is thread 2 of the prompt-tuning / default-mode plan from the
spike: thread 1 was the schema-description iteration (still in progress
on the spike page); thread 2 lets users carry the experiment around in
their own config while we converge on whether to flip the global default
in the schema.
Live-test surfaced a real bug: fast-mode results paired the resolved
lineage-root session_id with the raw FTS5 row's message_id. The (sid,
match_message_id) handle was self-inconsistent because the message
lives in the child (delegation/compression) session, not the parent —
so the agent's follow-up mode='guided' call hit
'around_message_id N not in session_id ROOT' and the drill failed.
Repro: ask the TUI to fast-search a topic that appears in a compressed
child session of the current lineage, then ask it to drill in. Today's
session is exactly that shape — message 18425 lives in
20260512_102257_d5048c (child) but fast returned its parent
20260511_101921_a7dd34 paired with id=18425.
Fix has two layers:
1) Fast-mode output now pairs session_id (raw FTS5 sid) with
match_message_id consistently. The lineage root is exposed as a
separate parent_session_id field (omitted when there's no
delegation/compression above). Dedup grouping still happens by
lineage root, so the user still sees one entry per conversation,
but the per-entry handle is now a valid pair the agent can hand
straight to mode='guided'.
- #15909 source-from-parent invariant preserved: source/model/title
still promote from the resolved parent for display.
2) Defensive rebind in mode='guided': if (a_sid, a_msg_id) doesn't
resolve, look up the actual owning session for a_msg_id. If it's a
descendant in the same lineage as a_sid, transparently rebind and
refetch. Records the rebind in a warning field on the returned
window (also flattened to top level for single-anchor responses).
Cross-lineage rebinds are refused — that path stays an error.
This keeps the tool forgiving for legacy callers, memory snippets,
or any other source that still emits the old (parent_sid, child_id)
shape.
3) Schema description tightened: explicit note that the agent must
pass (session_id, match_message_id) verbatim from a single fast
result — do NOT substitute parent_session_id (it's display-only).
Tests: updated the existing #15909 regression to assert the new pair
shape, plus four new tests:
- test_fast_pair_session_id_with_match_message_id (positive)
- test_fast_no_parent_session_id_field_when_session_is_already_root
(tidy output for non-delegation case)
- test_guided_rebinds_anchor_when_message_lives_in_descendant_session
(safety net fires correctly within a lineage)
- test_guided_does_not_rebind_across_lineages (refuses cross-lineage
rebind — no silent drill into unrelated session)
85/85 session_search + get_messages_around tests passing. Live-DB
smoke test against /tmp/state-smoke.db (snapshot of ~/.hermes/state.db)
confirms the user's failing case now rebinds:
success: True
top-level warning: 'around_message_id 18425 lives in
20260512_102257_d5048c (child of 20260511_101921_a7dd34);
rebound transparently'
returned session_id: 20260512_102257_d5048c
window before/after: 5 / 5
Extends mode='guided' to accept a list of anchors instead of a single
session+message pair. The agent calls fast with a wider limit, picks
the most promising K hits from the result list, and drills into all of
them in a single guided call — one window per anchor in the response.
This is the steering improvement flagged in the investigation page §6:
'5 results, pick top 3, strip tools' (strip-tools is a separate later
follow-up). Letting the agent inspect multiple windows in one turn
reduces the back-and-forth between fast and guided when the user
genuinely wants to look at several candidate sessions before committing.
Two input shapes (use one):
* Single anchor (back-compat): session_id + around_message_id
* Multi-anchor: anchors=[{session_id, around_message_id}, ...]
Single-anchor calls (the back-compat path) continue to work unchanged
and the response mirrors legacy fields at the top level when there's
exactly one window. Multi-anchor responses carry only 'windows' as the
authoritative list. Per-anchor failures (missing session, anchor not
in session, current-lineage rejection) become inline error entries
inside 'windows' rather than aborting the whole call — the agent can
still use successful drills if one anchor was malformed.
Window is shared across all anchors and clamped once to [1, 20].
Schema description updated to teach when to bump fast's limit higher
(5–10 for steering use cases) and how to compose anchors=[...] from
those results.
Tests:
- 7 new cases in TestGuidedModeMultiAnchor covering: two anchors both
succeed, one-fails-one-succeeds doesn't abort, single anchor via
anchors list normalises to legacy shape, empty/non-list anchors
return tool_error, window clamp shared across anchors, per-anchor
current-lineage rejection
- Brittle source-grep test updated to also pin the new anchors=
forwarding in run_agent.py
- 81/81 passing including the existing 65 + 7 new + brittle update + 9
hermes_state unit tests
End-to-end verified against real DB snapshot: 5 fast hits → top 3 as
anchors → 3 windows of 7 messages each (~100 kB total).
The original ceiling of 5 was sized for summary mode where each result
costs a parallel auxiliary LLM call (~30s wall total). With the steering
reframing of guided mode (see investigation page §6), fast becomes the
'discover and let the user pick' surface, and the user benefits from
seeing more candidates before committing to a drill-down.
Bumping the ceiling to 10 lets callers ask for a wider hit list when
that's the goal. Default stays at 3 (one-shot recall is unchanged).
Schema description updated to teach the LLM when to bump higher: 'when
the user wants to be in the retrieval loop and pick the right anchor for
a guided drill-down'.
For summary mode this means up to 10 parallel aux calls instead of 5;
the existing concurrency semaphore already bounds the actual wall time,
and most users won't hit the higher cap unless they're using fast.
65/65 passing.
Adds a third mode to session_search: guided returns a window of messages
around a specific message id in a specific session. No FTS5, no
auxiliary LLM, no 100k-char truncation — one DB query (~ms latency).
Designed to compose with mode=fast: the calling agent does cheap FTS5
discovery, picks a promising hit, then calls back with mode='guided',
session_id from the result, and around_message_id=match_message_id from
the same result. The agent gets the actual conversation around the
anchor — the back-and-forth that fast's snippet teases but doesn't
deliver, and that summary distils into prose at 30s+ wall-clock cost.
Mechanics:
- New _guided_drill_down() helper handles the guided dispatch path
- Mode aliases ('drill', 'drilldown', 'drill-down', 'anchor', 'around')
normalise to 'guided'
- Validates required args (session_id + around_message_id), session
existence, and anchor-in-session, returning specific tool_error
messages for each failure mode
- Window clamped silently to [1, 20] (matches existing limit-clamp pattern)
- Rejects drill-down into the calling session's lineage — those messages
are already in the agent's active context (same convention as fast/
summary's _resolve_to_parent skip)
- Anchor row carries 'anchor': true so the agent can locate it in the
ordered window without re-checking ids
- Returns messages_before/messages_after counts so the agent sees boundary
effects ('this is the first 3, no more available before') without a
follow-up call
Schema:
- mode enum extended to ['fast', 'summary', 'guided']
- Three new optional parameters: session_id, around_message_id, window
- Description rewritten to teach the discover→drill flow with example
question shapes per mode
Dispatch:
- run_agent.py's two session_search dispatch sites updated to forward
the new optional kwargs
- Brittle source-grep test in test_session_search.py updated for the
new dispatch shape and now also pins the guided-mode kwargs
Tests:
- 11 new cases in TestGuidedMode covering happy path, missing-arg errors,
window clamps (low + high), session-not-found, anchor-not-in-session,
session-boundary partial windows, current-lineage rejection, mode
aliases, schema advertising, and metadata propagation
- 74/74 passing including the existing 53 + 9 hermes_state unit tests
End-to-end verified against a real DB snapshot: fast → read
match_message_id+session_id off the top hit → guided returns 7 messages
(3 before + anchor + 3 after) at ~40 KB payload, vs summary's ~220 KB
auxiliary-LLM input for the same query.
Adds 'match_message_id' to each fast-mode result entry, carrying through
the FTS5 message id (already populated in the underlying search_messages
result; just unsurfaced until now).
This is the composition handle for the upcoming mode='guided' drill-down:
the calling agent reads a fast hit, picks a promising session, and passes
session_id + match_message_id back as around_message_id for an anchored
window.
Lossless for non-guided callers (additive field, no schema changes).
One new test (test_fast_mode_includes_match_message_id_for_guided_drilldown).
63/63 passing.
Reverses the default introduced by the salvaged dual-mode commit.
Why: profiled four representative queries against a real 280-session
state.db (workspace harness, not committed). Summary mode is 1,299x-6,293x
slower than fast (median ~30s vs ~10ms; 99%+ in the auxiliary LLM call) and
produces 2.9x-3.9x larger result blobs, but it answers a materially different
question. The user's typical 'what did we work on for X?' is the summary
question — fast surfaces only what FTS5 directly matched while summary
surfaces cross-session synthesis (e.g. work sessions referenced inside
the matched cron jobs). Backwards-compatible default; fast remains
opt-in for cheap discovery via mode='fast'.
Changes:
- tools/session_search_tool.py: default parameter, defensive coercion
fallbacks, and registry handler all default to 'summary'. Schema
description rewritten with measured trade-offs and the 'use fast for
discovery, summary for recall' framing.
- run_agent.py: both direct call sites mirror the new default.
- tests/tools/test_session_search.py: split the old default-test into
test_default_search_returns_summary_mode_recap (asserts new default)
and test_explicit_fast_mode_returns_snippets... (covers fast path
without mocking the default away). Invalid-mode test now asserts
fallback to summary. Source-grep test updated.
Add mode parameter to session_search tool supporting two modes:
- fast (default): returns FTS5 snippets + context immediately (~0.02s),
no LLM call — ideal for quick recall lookups
- summary: preserves original behavior with LLM-generated session
summaries (~10-30s) — use when fast mode is insufficient
Changes:
- tools/session_search_tool.py: implement fast mode path that returns
FTS hits with snippets/context without calling auxiliary model;
add mode parameter to schema (enum: fast|summary); apply parent
session source/metadata resolution in fast mode (same pattern
as upstream fix 6b4ccb9b1 in summary mode)
- run_agent.py: pass mode argument from function_args in two call sites
(direct tool call + subagent path)
- tests/tools/test_session_search.py: add test coverage for fast mode
output format, summary mode preservation, backwards compatibility,
and run_agent.py mode forwarding verification
The tool schema description is updated to recommend fast-first usage.
SQLite's WAL mode requires shared-memory (mmap) coordination and fcntl
byte-range locks that don't reliably work on network filesystems. Upstream
documents this explicitly:
https://www.sqlite.org/wal.html#sometimes_queries_return_sqlite_busy_in_wal_mode
On NFS / SMB / some FUSE mounts / WSL1, 'PRAGMA journal_mode=WAL' raises
'sqlite3.OperationalError: locking protocol' (SQLITE_PROTOCOL). Before
this change, every feature backed by state.db or kanban.db broke silently:
- /resume, /title, /history, /branch returned 'Session database not
available.' with no cause
- gateway logged the init failure at DEBUG (invisible in errors.log)
- kanban dispatcher crashed every 60s, driving the known migration race
(duplicate column name: consecutive_failures, #21708 / #21374)
Changes:
- hermes_state.apply_wal_with_fallback(): shared helper that tries WAL
and falls back to DELETE on SQLITE_PROTOCOL-style errors with one
WARNING explaining why
- hermes_state.get_last_init_error() + format_session_db_unavailable():
capture the init failure cause and surface it in user-facing strings
(with an NFS/SMB pointer for 'locking protocol')
- hermes_cli/kanban_db.connect(): use the shared helper
- gateway/run.py: bump SessionDB init failure log DEBUG -> WARNING
(matches cli.py's existing correct behavior)
- cli.py (4 sites) + gateway/run.py (5 sites): replace bare
'Session database not available.' with format_session_db_unavailable()
Tests: 12 new tests in tests/test_hermes_state_wal_fallback.py + 1 new
test in tests/hermes_cli/test_kanban_db.py. Existing suites (state,
kanban, gateway, cli) remain green for all tests unrelated to pre-existing
failures on main.
Evidence: real-world user on NFSv3 mount (172.26.224.200:d2dfac12/home,
local_lock=none) reporting 'Session database not available.' on /resume;
'locking protocol' appears in 4 distinct log entries across backup,
kanban, TUI, and CLI paths in the same session.
closes#22032
When a delegation child session (e.g. source='telegram') contains the
FTS5 hit but _resolve_to_parent() maps it to a different root session
(source='api_server'), the result entry was still reporting the child's
source because the loop discarded session_meta as `_` and fell back to
match_info.get('source'), which carries the child session's value.
Use the resolved parent's session_meta for source, model, and started_at
with match_info as a fallback, so the output accurately reflects the
session the user actually interacted with.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- order session_search recent-mode results by last activity instead of session start time
- add an opt-in `order_by_last_active` path to `SessionDB.list_sessions_rich`
- add regression coverage for both the database ordering and recent-mode call path
Models (especially open-source like qwen3.5-plus) may send non-int values
for the limit parameter — None (JSON null), string, or even a type object.
This caused TypeError: '<=' not supported between instances of 'int' and
'type' when the value reached min()/comparison operations.
Changes:
- Add defensive int coercion at session_search() entry with fallback to 3
- Clamp limit to [1, 5] range (was only capped at 5, not floored)
- Add tests for None, type object, string, negative, and zero limit values
Reported by community user ludoSifu via Discord.
Three-tier match strategy for _truncate_around_matches():
1. Full-phrase search (exact query string positions)
2. Proximity co-occurrence (all terms within 200 chars)
3. Individual terms (fallback, preserves existing behavior)
Sliding window picks the start offset covering the most matches.
Moved inline import re to module level.
Co-authored-by: Al Sayed Hoota <78100282+AlsayedHoota@users.noreply.github.com>
* Fix#3409: Add fallback to session_search to prevent false negatives on summarization failure
Fixes#3409. When the auxiliary summarizer fails or returns None, the tool now returns a raw fallback preview of the matched session instead of silently dropping it and returning an empty list
* fix: clean up fallback logic — separate exception handling from preview
Restructure the loop: handle exceptions first (log + nullify), build
entry dict once, then branch on result truthiness. Removes duplicated
field assignments and makes the control flow linear.
---------
Co-authored-by: devorun <130918800+devorun@users.noreply.github.com>
Salvage of #3389 by @binhnt92 with reasoning fallback and retry logic added on top.
All 7 auxiliary LLM call sites now use extract_content_or_reasoning() which mirrors the main agent loop's behavior: extract content, strip think blocks, fall back to structured reasoning fields, retry on empty.
Closes#3389.
When third-party tools (Paperclip orchestrator, etc.) spawn hermes chat
as a subprocess, their sessions pollute user session history and search.
- hermes chat --source <tag> (also HERMES_SESSION_SOURCE env var)
- exclude_sources parameter on list_sessions_rich() and search_messages()
- Sessions with source=tool hidden from sessions list/browse/search
- Third-party adapters pass --source tool to isolate agent sessions
Cherry-picked from PR #3208 by HenkDz.
Co-authored-by: Henkey <noonou7@gmail.com>
In gateway mode, async tools (vision_analyze, web_extract, session_search)
deadlock because _run_async() spawns a thread with asyncio.run(), creating
a new event loop, but _get_cached_client() returns an AsyncOpenAI client
bound to a different loop. httpx.AsyncClient cannot work across event loop
boundaries, causing await client.chat.completions.create() to hang forever.
Fix: include the event loop identity in the async client cache key so each
loop gets its own AsyncOpenAI instance. Also fix session_search_tool.py
which had its own broken asyncio.run()-in-thread pattern — now uses the
centralized _run_async() bridge.
When session_search is called without a query (or with an empty query),
it now returns metadata for the most recent sessions instead of erroring.
This lets the agent quickly see what was worked on recently without
needing specific keywords.
Returns for each session: session_id, title, source, started_at,
last_active, message_count, preview (first user message).
Zero LLM cost — pure DB query. Current session lineage and child
delegation sessions are excluded.
The agent can then keyword-search specific sessions if it needs
deeper context from any of them.
Cherry-picked from PR #2201 by @Gutslabs.
session_search resolved hits to parent/root sessions but only excluded
the exact current_session_id. If the active session was a child
continuation (compression/delegation), its parent could still appear
as a 'past' conversation result.
Fix: resolve current_session_id to its lineage root before filtering,
so the entire active lineage (parent and children) is excluded.
- Add 'emoji' field to ToolEntry and 'get_emoji()' to ToolRegistry
- Add emoji= to all 50+ registry.register() calls across tool files
- Add get_tool_emoji() helper in agent/display.py with 3-tier resolution:
skin override → registry default → hardcoded fallback
- Replace hardcoded emoji maps in run_agent.py, delegate_tool.py, and
gateway/run.py with centralized get_tool_emoji() calls
- Add 'tool_emojis' field to SkinConfig so skins can override per-tool
emojis (e.g. ares skin could use swords instead of wrenches)
- Add 11 tests (5 registry emoji, 6 display/skin integration)
- Update AGENTS.md skin docs table
Based on the approach from PR #1061 by ForgingAlex (emoji centralization
in registry). This salvage fixes several issues from the original:
- Does NOT split the cronjob tool (which would crash on missing schemas)
- Does NOT change image_generate toolset/requires_env/is_async
- Does NOT delete existing tests
- Completes the centralization (gateway/run.py was missed)
- Hooks into the skin system for full customizability
Remove diary-style memory framing from the system prompt and memory tool
schema, explicitly steer task/session logs to session_search, and clarify
that session_search is for cross-session recall after checking the current
conversation first. Add regression tests for the updated guidance text.
Add centralized call_llm() and async_call_llm() functions that own the
full LLM request lifecycle:
1. Resolve provider + model from task config or explicit args
2. Get or create a cached client for that provider
3. Format request args (max_tokens handling, provider extra_body)
4. Make the API call with max_tokens/max_completion_tokens retry
5. Return the response
Config: expanded auxiliary section with provider:model slots for all
tasks (compression, vision, web_extract, session_search, skills_hub,
mcp, flush_memories). Config version bumped to 7.
Migrated all auxiliary consumers:
- context_compressor.py: uses call_llm(task='compression')
- vision_tools.py: uses async_call_llm(task='vision')
- web_tools.py: uses async_call_llm(task='web_extract')
- session_search_tool.py: uses async_call_llm(task='session_search')
- browser_tool.py: uses call_llm(task='vision'/'web_extract')
- mcp_tool.py: uses call_llm(task='mcp')
- skills_guard.py: uses call_llm(provider='openrouter')
- run_agent.py flush_memories: uses call_llm(task='flush_memories')
Tests updated for context_compressor and MCP tool. Some test mocks
still need updating (15 remaining failures from mock pattern changes,
2 pre-existing).
Authored by aydnOktay. Adds TimeoutError handling for session summarization,
better exception specificity in _format_timestamp, defensive try/except in
_resolve_to_parent, and type hints.
session_search was returning the current session if it matched the
query, which is redundant — the agent already has the current
conversation context. This wasted an LLM summarization call and a
result slot.
Added current_session_id parameter to session_search(). The agent
passes self.session_id and the search filters out any results where
either the raw or parent-resolved session ID matches. Both the raw
match and the parent-resolved match are checked to handle child
sessions from delegation.
Two tests added verifying the exclusion works and that other
sessions are still returned.
- Enhanced Codex model discovery by fetching available models from the API, with fallback to local cache and defaults.
- Updated the context compressor's summary target tokens to 2500 for improved performance.
- Added external credential detection for Codex CLI to streamline authentication.
- Refactored various components to ensure consistent handling of authentication and model selection across the application.
- Added _max_tokens_param method in AIAgent to return appropriate max tokens parameter based on the provider (OpenAI vs. others).
- Updated API calls in AIAgent to utilize the new max tokens handling.
- Introduced auxiliary_max_tokens_param function in auxiliary_client for consistent max tokens management across auxiliary clients.
- Refactored multiple tools to use auxiliary_max_tokens_param for improved compatibility with different models and providers.
- Added functionality to include product attribution tags for Nous Portal in auxiliary API calls.
- Introduced a mechanism to determine if the auxiliary client is backed by Nous Portal, affecting the extra body of requests.
- Updated various tools to utilize the new extra body configuration for enhanced tracking in API calls.
- Added a new function to resolve child sessions to their parent, improving session grouping and deduplication.
- Refactored session summarization to run in parallel, enhancing performance and responsiveness.
- Updated search syntax documentation to clarify usage of keywords and phrases for better search results.
- Introduced a new `_format_timestamp` function to convert Unix timestamps and ISO strings into a human-readable date format.
- Updated the session metadata handling to use the new formatting function for improved clarity in session start dates.
- Adjusted the output structure to reflect the change from "Session started" to "Session date" for better user understanding.
- Introduced MEMORY_GUIDANCE and SESSION_SEARCH_GUIDANCE to improve agent's contextual awareness and proactive assistance.
- Updated AIAgent to conditionally include tool-aware guidance in prompts based on available tools.
- Enhanced descriptions in memory and session search schemas for clearer user instructions on when to utilize these features.
- Introduced a new DebugSession class in tools/debug_helpers.py to centralize debug logging functionality, replacing duplicated code across various tool modules.
- Updated image_generation_tool.py, mixture_of_agents_tool.py, vision_tools.py, web_tools.py, and others to utilize the new DebugSession for logging tool calls and saving debug logs.
- Enhanced maintainability and consistency in debug logging practices across the codebase.
yoniebans