Dev/0.4.54 (#683)

* smart agent improvements, websocket improvements

* smart agent enhance, websocket performance, parallel bash handling

* add claude-sonnet-4-6, sonnet46 alias, --smart CLI flag, update docs

* feat(agent-cards): add runtime MCP targets via mcp_connect

* chore(docs): bump docs submodule for mcp_connect docs

* web search for anthropic
history webclear command
improve smart agent  handling

Author: evalstate

docs

@@ -7,6 +7,7 @@ A loader validates fields based on `type` and loads a single file or a directory
 optional/experimental and described in a separate spec.
 AgentCards now support an optional `description` field used for tool descriptions when
 agents are exposed as tools (MCP or agent-as-tool wiring).
+AgentCards may declare runtime MCP targets via `mcp_connect` (`target` + optional `name`).
 AgentCards may enable local shell execution via `shell: true` with optional `cwd`.
 AgentCards support `tool_only: true` to prevent exposure as first-class agents while
 still allowing use as tools (useful for helper agents in `.fast-agent/tool-cards/`).
@@ -115,6 +116,7 @@ Allowed fields:
 - `name`, `instruction`, `description`, `default`, `tool_only`
 - `agents` (agents-as-tools)
 - `servers`, `tools`, `resources`, `prompts`, `skills`
+- `mcp_connect` (runtime MCP targets; `target` required, `name` optional)
 - `model`, `use_history`, `request_params`, `human_input`, `api_key`
 - `history_source`, `history_merge_target`
 - `max_parallel`, `child_timeout_sec`, `max_display_instances`

plan/agent-card-rfc.md

@@ -0,0 +1,195 @@
+---
+title: "Session Size Indicator in /session list"
+status: draft
+---
+
+# Session Size Indicator in `/session list`
+
+## Goal
+
+Add a compact visual size indicator to session list output (interactive + ACP markdown),
+similar in spirit to history density shading.
+
+Example target UX:
+
+- small session: `░`
+- medium session: `▒`
+- large session: `▓`
+- very large session: `█`
+
+This should make large sessions obvious at a glance without opening each one.
+
+---
+
+## Current behavior and constraints
+
+1. Session metadata is saved to `session.json` via `Session._save_metadata()`.
+2. Session history autosave runs from the `after_turn_complete` hook (`save_session_history`).
+3. `/session list` rendering paths:
+   - interactive/TUI: `commands/handlers/sessions.py::_build_session_entries(...)`
+   - ACP markdown: `commands/renderers/session_markdown.py`, fed by
+     `session/formatting.py::format_session_entries(...)`
+4. Current list rows already include timestamp, pin state, agent count, summary.
+
+Design implication: compute/store a lightweight turn count during autosave and read it from
+`session.json` during listing (no history file parsing during list).
+
+---
+
+## Proposed metadata additions
+
+Add optional metadata keys in `session.json`:
+
+- `turn_count_by_agent: dict[str, int]`
+- `turn_count_total: int`
+
+Notes:
+
+- `turn_count_total` is the value used for list glyphs.
+- Missing keys are valid for old sessions (fallback indicator).
+
+---
+
+## Turn counting rule
+
+Use the same turn boundary semantics as conversation summaries:
+
+- a turn starts on a `user` message with no `tool_results`
+
+Implementation should use `split_into_turns(...)` from
+`fast_agent.types.conversation_summary` for consistency.
+
+---
+
+## Indicator mapping (initial thresholds)
+
+Define a small helper (in `session/formatting.py` or nearby) that maps `turn_count_total`
+to a single character.
+
+Initial mapping proposal:
+
+- missing/unknown: `·`
+- `0`: `·`
+- `1-4`: `░`
+- `5-14`: `▒`
+- `15-39`: `▓`
+- `40+`: `█`
+
+Thresholds can be tuned later based on real usage.
+
+---
+
+## Implementation plan
+
+## 1) Persist turn counts during save
+
+Files:
+
+- `src/fast_agent/session/session_manager.py`
+
+Changes:
+
+1. In `Session.save_history(...)` after saving history file and resolving `agent_name`:
+   - compute `agent_turn_count` from `agent.message_history`
+   - update `metadata["turn_count_by_agent"][agent_name]`
+   - compute/update `metadata["turn_count_total"]` as sum of per-agent counts
+2. Keep behavior safe when agent has no name or malformed metadata.
+3. Ensure this remains part of existing `_save_metadata()` call path.
+
+## 2) Preserve counts on fork
+
+Files:
+
+- `src/fast_agent/session/session_manager.py`
+
+Changes:
+
+1. In `fork_current_session(...)`, copy over `turn_count_by_agent` and `turn_count_total`
+   (or recompute from copied map if safer).
+
+## 3) Thread counts into list summaries
+
+Files:
+
+- `src/fast_agent/session/formatting.py`
+
+Changes:
+
+1. Extend `SessionEntrySummary` with optional `turn_count` and `size_indicator`.
+2. In `build_session_entry_summaries(...)`, read `turn_count_total` from metadata.
+3. Compute `size_indicator` from helper mapping.
+4. For old sessions without metadata, default to unknown indicator.
+
+## 4) Render indicator in interactive list
+
+Files:
+
+- `src/fast_agent/commands/handlers/sessions.py`
+
+Changes:
+
+1. In `_build_session_entries(...)`, add `entry.size_indicator` before session name,
+   dim-styled so it is informative but not noisy.
+
+## 5) Render indicator in compact/markdown list
+
+Files:
+
+- `src/fast_agent/session/formatting.py`
+
+Changes:
+
+1. In `format_session_entries(..., mode="compact")`, prepend indicator to each line
+   so ACP markdown rendering automatically includes it.
+
+No direct change should be required in `session_markdown.py` if compact lines already
+contain the indicator.
+
+---
+
+## Backward compatibility
+
+1. Existing sessions without new metadata continue to list correctly.
+2. Unknown/missing count shows neutral marker (`·`).
+3. No migration step required.
+
+---
+
+## Testing plan
+
+## Unit tests
+
+1. `tests/unit/fast_agent/session/test_session_formatting.py`
+   - add/adjust assertions for indicator presence in compact/verbose outputs
+   - include edge cases around threshold boundaries
+2. Add/extend `session_manager` unit test(s)
+   - verify `turn_count_by_agent` and `turn_count_total` are written on save
+   - verify malformed metadata is handled robustly
+
+## Integration tests
+
+1. `tests/integration/sessions/test_sessions.py`
+   - assert new metadata keys appear in `session.json` after autosave
+2. ACP session list integration test
+   - ensure response contains indicator in list lines
+
+---
+
+## Risks / trade-offs
+
+1. **Accuracy vs cost:** storing turn counts is fast and cheap; parsing all histories on list
+   would be more accurate for legacy edge cases but slower.
+2. **Definition drift:** if turn definition changes elsewhere, this feature must stay aligned
+   by relying on shared split helper.
+3. **Visual noise:** indicators should be dim and stable; avoid overloading line with too many
+   symbols.
+
+---
+
+## Rollout sequence
+
+1. Land metadata persistence + tests.
+2. Land formatting/rendering + tests.
+3. Validate in both interactive prompt and ACP `/session list`.
+4. Tune thresholds if needed after initial usage.
+

plan/session-size.md

@@ -21,7 +21,7 @@ dependencies = [
     "pyyaml>=6.0.2",
     "rich>=14.3.1",
     "typer>=0.21.1",
-    "anthropic>=0.78.0",
+    "anthropic>=0.80.0",
     "openai[aiohttp]>=2.17.0",
     "prompt-toolkit>=3.0.52",
     "aiohttp>=3.13.2",

pyproject.toml

@@ -0,0 +1,88 @@
+<AgentCards>
+---
+
+# Agent Card (type: `agent`)
+
+## Format
+- **Markdown** with YAML frontmatter + body, or **YAML** only.
+- **Body = system/developer instruction.**
+  - Optional first non-empty line `---SYSTEM` is stripped.
+- `instruction:` field **or** body may define the instruction (not both).
+- If neither is present, the **default instruction** is used.
+- **Invocation:** the card defines the agent; you invoke it later with a **user message** (first user turn).
+  - `messages:` is **history files**, not the invocation message.
+
+---
+
+## Main fields (frontmatter, type = `agent`)
+- `name` — string; defaults to file stem.
+- `description` — optional summary.
+- `type` — `"agent"` (default if omitted).
+- `model` — model ID.
+- `instruction` — system/developer prompt string (mutually exclusive with body).
+- `skills` — list of skills. **Disable all skills:** `skills: []`.
+- `servers` — list of configured MCP server names.
+- `tools` / `resources` / `prompts` — map: `server_name -> [allowed_items]`.
+- `mcp_connect` — optional runtime MCP targets resolved at startup.
+  - entries require `target` and may include optional `name`.
+  - target forms: `https://...`, `@scope/pkg`, `npx ...`, `uvx ...`, or stdio command.
+- `agents` — list of child agents (Agents-as-Tools).
+- `use_history` — bool (default `true`).
+- `messages` — path or list of history files (relative to card directory).
+- `request_params` — request/model overrides.
+- `human_input` — bool (enable human input tool).
+- `shell` — bool (enable shell); `cwd` optional.
+- `default` — marks this agent as the `smart` tool target when the path resolves multiple cards. First `default: true` non-`tool_only` agent wins; if none, the first non-`tool_only` agent is used.
+- `tool_only` — excludes this agent from default selection; it can only be invoked by other agents as a tool.
+
+---
+
+## Instruction templates (placeholders)
+You can insert these in the **body** or `instruction:`.
+
+| Placeholder | Meaning |
+|---|---|
+| `\{{currentDate}}` | Current date (e.g., “17 December 2025”) |
+| `\{{hostPlatform}}` | Host platform string |
+| `\{{pythonVer}}` | Python version |
+| `\{{workspaceRoot}}` | Workspace root path (if available) |
+| `\{{env}}` | Environment summary (client, host, workspace) |
+| `\{{agentName}}` | Current agent name |
+| `\{{agentType}}` | Current agent type |
+| `\{{agentCardPath}}` | Source AgentCard path (if loaded from card) |
+| `\{{agentCardDir}}` | Directory containing the source AgentCard |
+| `\{{serverInstructions}}` | MCP server instructions (if any) |
+| `\{{agentSkills}}` | Formatted skill descriptions |
+
+---
+
+## Content includes (inline)
+- `\{{url:https://...}}` — fetch and inline URL content.
+- `\{{file:relative/path}}` — inline file content (error if missing).
+- `\{{file_silent:relative/path}}` — inline file content, **empty if missing**.
+
+**Note:** file paths are **relative** (resolved against `workspaceRoot` when available).
+
+---
+
+## Minimal example (Markdown)
+
+```md
+---
+name: my_agent
+description: Focused helper
+model: gpt-oss
+skills: []   # disable skills
+use_history: true
+---
+
+You are a concise assistant.
+
+\{{env}}
+\{{currentDate}}
+\{{file:docs/house-style.md}}
+```
+
+---
+
+</AgentCards>

resources/shared/smart_agent_cards.md

@@ -0,0 +1,32 @@
+You are a helpful AI Agent.
+
+You have the ability to create sub-agents and delegate tasks to them. 
+
+Information about how to do so is below. Pre-existing cards may be in the `fast-agent environment` directories. You may issue
+multiple calls in parallel to new or existing AgentCard definitions.
+
+{{internal:smart_agent_cards}}
+
+{{serverInstructions}}
+{{agentSkills}}
+{{file_silent:AGENTS.md}}
+{{env}}
+
+fast-agent environment paths:
+- Environment root: {{environmentDir}}
+- Agent cards: {{environmentAgentCardsDir}}
+- Tool cards: {{environmentToolCardsDir}}
+
+Current agent identity:
+- Name: {{agentName}}
+- Type: {{agentType}}
+- AgentCard path: {{agentCardPath}}
+- AgentCard directory: {{agentCardDir}}
+
+Use the smart tool to load AgentCards temporarily when you need extra agents.
+Use validate to check AgentCard files before running them.
+When a card needs MCP servers that are not preconfigured in `fastagent.config.yaml`,
+declare them with `mcp_connect` entries (`target` + optional `name`). Prefer explicit
+`name` values when collisions are possible.
+
+The current date is {{currentDate}}.

resources/shared/smart_prompt.md

@@ -88,7 +88,10 @@
 from fast_agent.context import Context
 from fast_agent.core.fastagent import AgentInstance
 from fast_agent.core.instruction_refresh import McpInstructionCapable, build_instruction
-from fast_agent.core.instruction_utils import get_instruction_template
+from fast_agent.core.instruction_utils import (
+    build_agent_instruction_context,
+    get_instruction_template,
+)
 from fast_agent.core.logging.logger import get_logger
 from fast_agent.core.prompt_templates import enrich_with_environment_context
 from fast_agent.interfaces import (
@@ -660,6 +663,8 @@ async def _resolve_instruction_for_session(
             if agent.instruction_context:
                 effective_context = dict(agent.instruction_context)
 
+        effective_context = build_agent_instruction_context(agent, effective_context)
+
         return await build_instruction(
             template,
             aggregator=aggregator,
@@ -780,7 +785,8 @@ async def _refresh_session_state(
         for agent_name, agent in instance.agents.items():
             if isinstance(agent, InstructionContextCapable):
                 try:
-                    agent.set_instruction_context(prompt_context)
+                    context_with_agent = build_agent_instruction_context(agent, prompt_context)
+                    agent.set_instruction_context(context_with_agent)
                 except Exception as exc:
                     logger.warning(
                         "Failed to set instruction context on agent",
@@ -1474,7 +1480,8 @@ async def _initialize_session_state(
         for agent_name, agent in instance.agents.items():
             if isinstance(agent, InstructionContextCapable):
                 try:
-                    agent.set_instruction_context(session_context)
+                    context_with_agent = build_agent_instruction_context(agent, session_context)
+                    agent.set_instruction_context(context_with_agent)
                 except Exception as e:
                     logger.warning(f"Failed to set instruction context on agent {agent_name}: {e}")