feat: sturdier session handles — issue IDs first, structured mcp_session status

[naji247]

Session handles are easy for callers to miss when they arrive at the tail of a long result — clients that truncate large tool outputs can drop the issuance notice entirely, and agents then start new sessions instead of continuing the one they were given. This change makes the handle mechanism sturdier and easier for agents to consume:

• IDs are issued at the start of the response. The issuance text block is now the first content element instead of the last, so it survives client-side truncation of long results.
• session_id and agent_id are now required parameters with an explicit value contract. session_id takes one of two values — the ses_ ID issued for the task, or the literal start to begin a new one — declared with a validation pattern in the schema (^(start|ses_[0-9A-Za-z]{27})$). Every call states its session explicitly, so sessions never split by accident. Servers keep accepting calls that omit the parameters (treated as the start of a new task), so requiredness is enforced only by schema-aware clients and nothing existing breaks server-side.
• mcp_session replaces _mcp_instructions as the structured mirror in structuredContent, declared in each tool's output schema. It carries a machine-readable status enum (issued / active / unrecognized) instead of prose — every response state an agent can encounter is pre-announced in the schema.
• Leaner, self-describing parameter copy. The session_id and agent_id descriptions now explain the mechanism in terms of what this server does, pre-announce both text-block headers so responses match the schema's stated contract, and collapse the two agent_id description variants into one.
• Recovery is explicit. An unrecognized value is reported both as mcp_session.status: "unrecognized" and as a leading text block, with the recovery path (re-send the earlier ID, or send start if none was issued) stated in the schema.

Breaking wire changes (for consumers that assert on response internals or schemas): the structuredContent mirror key is renamed _mcp_instructions → mcp_session; its instructions string member is removed in favor of status; the issuance text block moved from the last to the first content position and its header text changed ([session_id issued …] / [session_id unrecognized …]); session_id and agent_id now appear in each tool's required array, and session_id declares the validation pattern above.

Version bumped to 2.1.0.

Testing

• uv run --no-sync pytest: 815 passed / 26 skipped
• uvx ruff check ., uvx ruff format --check ., uvx mypy src/agentcat: no new findings vs main (pre-existing repo-wide debt unchanged; all touched files clean)

Cross-SDK note: this lands the same strings and wire shape in all three SDKs, byte-identical where applicable. Sibling PRs: agentcathq/agentcat-typescript-sdk#67 · agentcathq/agentcat-go-sdk#13