Bug: Messages.stream() got an unexpected keyword argument 'instructions' when continuing from a successful vision_analyze aux call

Summary

In v0.14.0, the first main-provider streaming API call immediately after a successful vision_analyze auxiliary call fails client-side with TypeError: Messages.stream() got an unexpected keyword argument 'instructions'. The Anthropic Python SDK uses system=, not instructions= — the instructions= keyword belongs to OpenAI's Responses/Assistants API. The bug is non-retryable, propagates through the full fallback chain, and the oversized image that frequently triggers vision retries gets stuck in session memory so the loop is unrecoverable without killing the session.

Two occurrences in a 1-second window logged on 2026-05-24 00:24:38 CDT, then never reproduced across the same session's subsequent ~95 API calls. Suggests state leak from the aux-vision path into the next main-loop streaming kwargs build, not a deterministic adapter bug.

Environment

• Hermes Agent: v0.14.0 (commit 72ff3e909, pulled 2026-05-23 22:30:23 CDT)
• Working state before the regression: commit 4e2c66a09 (May 22 00:00 CDT, 474 commits earlier on main)
• Host OS: macOS 26.5 (Mac M5 Max, 128 GB)
• Anthropic Python SDK: 0.87.0
• Gateway: healthy, port 11435 (PID 13888 at time of failure)
• Profile: io (custom skill set + cron jobs)
• Primary model: claude-opus-4-7
• Fallback chain: claude-sonnet-4-6 → gpt-4o-mini → qwen3.6:35b
• Failing model: claude-sonnet-4-6 (Anthropic provider, native anthropic_messages adapter)

Bisect range for upstream

Working ↔ broken in main:

git log 4e2c66a09..72ff3e909 --oneline

474 commits between. The bug was introduced somewhere in this range. We were unable to bisect locally without a deterministic repro, but the call-path evidence narrows it.

Reproduction (suggestive, not deterministic)

1. Update Hermes to commit 72ff3e909 (or any v0.14.0 from 2026-05-23 22:30 onward through ~07:38 next morning).
2. Configure a fallback chain with at least one Anthropic model: e.g. claude-opus-4-7 → claude-sonnet-4-6 → gpt-4o-mini → qwen3.6:35b.
3. In a CLI session, call vision_analyze on a local image where:
   • The image is under 5 MB (so the vision aux call succeeds, returning a text analysis)
   • The main provider is set to anthropic (so the auto-detect routes vision to the main provider)
4. After vision_analyze returns text, the next main-loop turn's streaming call fails with the TypeError above.

Failure window observed in our case: first 2 turns after a successful vision_analyze. After that, the same session's subsequent ~95 Anthropic streaming calls succeeded normally. Suggests transient kwargs-build state leak, not a persistent code-path defect.

Actual error (verbatim from session log)

2026-05-24 00:24:13,302 INFO [20260523_222951_624a55] agent.auxiliary_client: Vision auto-detect: using main provider anthropic (claude-sonnet-4-6)
2026-05-24 00:24:38,421 INFO [20260523_222951_624a55] tools.vision_tools: Image analysis completed (3514 characters)
2026-05-24 00:24:38,482 INFO agent.chat_completion_helpers: Streaming failed before delivery: Messages.stream() got an unexpected keyword argument 'instructions'
2026-05-24 00:24:38,483 WARNING [20260523_222951_624a55] agent.conversation_loop: API call failed (attempt 1/3) error_type=TypeError thread=Thread-654 (run_agent):6282440704 provider=anthropic base_url=https://api.anthropic.com model=claude-sonnet-4-6 summary=Messages.stream() got an unexpected keyword argument 'instructions'
2026-05-24 00:24:38,492 INFO [20260523_222951_624a55] root: Fallback activated: claude-sonnet-4-6 → qwen3.6:35b (custom:ollama)

Note the sequence — vision_analyze succeeded at 00:24:38.421, the very next streaming call to the same model failed at 00:24:38.482 (61 ms later). The image was 1.3 MB (well under Anthropic's 5 MB cap), so the size issue is a separate concern; this bug is purely about the kwargs leak.

After the failure, Hermes falls back through the chain. The next two retry attempts hit identical TypeErrors before the fallback engages — the bad kwargs persist across retry attempts of the same model.

Expected behavior

anthropic.resources.messages.Messages.stream() signature accepts system=, not instructions= (verified against SDK 0.87.0):

>>> import inspect
>>> from anthropic.resources.messages import Messages
>>> inspect.signature(Messages.stream).parameters.keys()
dict_keys(['self', 'max_tokens', 'messages', 'model', ..., 'system', ...])
# no 'instructions' parameter

So either:

1. A code path is leaking instructions= (an OpenAI Responses/Codex kwarg) into the Anthropic api_kwargs build, OR
2. A shim like CodexCompletionsAdapter in agent/auxiliary_client.py (line 629) is being mistakenly applied to an Anthropic-targeted client after a vision aux call.

Suspected root cause

The CodexCompletionsAdapter in agent/auxiliary_client.py:629 constructs resp_kwargs with "instructions": instructions (line 659) for Codex Responses API targets. If the wrong client path is taken — e.g. an Anthropic main-provider call accidentally uses this adapter, or its resp_kwargs get reused as api_kwargs for _anthropic_client.messages.stream(**api_kwargs) in agent/chat_completion_helpers.py:1668 — the kwargs collision produces this exact error.

The error fires only after the vision aux path runs. The vision path goes through agent/auxiliary_client.py and may share state with the subsequent main-loop call.

Impact

• Severity: High. Sessions with both vision-tool usage AND an Anthropic-tier fallback chain become unrecoverable once a session hits this state if the offending payload remains in session memory (e.g. an oversized retried image).
• Cost: In our case, a single failing user turn produced ~9 hours of retry-loop activity and ~50,000 tokens of fallback churn before being killed.
• Detectability: Silent. The CLI keeps responding (via the qwen-local fallback), so the user doesn't realize the fallback chain is broken until they notice degraded behavior.

Workaround

No client-side workaround. Mitigations:

• Remove Anthropic models from positions 2+ in the fallback chain (Sonnet 4-6 as Fallback 1 currently re-fails immediately because it shares the failing code path).
• Kill the affected session and start fresh: hermes sessions delete <session_id>. The offending state does not survive.
• Avoid using vision_analyze in any session that might trigger an Anthropic fallback until this is fixed.

Related: secondary issue (already known, may warrant separate filing)

The same session also surfaced HTTP 400: image exceeds 5 MB maximum when a Retina screenshot was sent. The 5 MB cap is Anthropic's, not a Hermes bug, but Hermes has no preflight downscale step — an oversized image stays in session memory and replays on every retry, making the loop unrecoverable. Suggested enhancement: preflight downscale to under 5 MB before send, OR refuse with a clear actionable error message instead of looping. (Open to splitting this into its own issue if preferred.)

Session reference (for upstream investigation)

• Session ID: 20260523_222951_624a55
• Session title: "Checking In With AI"
• Total session duration: ~9 hours from first fail to manual kill
• Two TypeError occurrences logged at:
  • 2026-05-24 00:24:38,482 CDT (first)
  • 2026-05-24 00:24:38,483 CDT (second, immediately retry)
• Subsequent ~95 Anthropic streaming calls in the same session did NOT reproduce the bug — the kwargs leak appears window-limited

Forensic logs (full traces available on request)

Available locally on reporter's machine:

• ~/.hermes/profiles/io/logs/agent.log.2 — full session trace
• ~/.hermes/profiles/io/logs/errors.log — error summaries
• Session DB row for 20260523_222951_624a55

Happy to email/Slack/upload traces to a Hermes maintainer for deeper diagnosis. Cannot reproduce on demand, so this is a reactive bug report rather than a deterministic repro.

Reporter context: End-user, not a Hermes contributor. Caught the bug from a real-world Iolana session. Bisect range provided to save the maintainer team an investigation step.