AgentCat v2.1.0 — sturdier session handles: IDs issued first, structured mcp_session status

AgentCat v2.1.0 makes explicit session handles sturdier and easier for agents to consume. There are no track() API changes — the delta is in the wire contract between your server and the agent.

What's new

• 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. Published events are unaffected: they still carry your original, undecorated response.
• session_id is required, with an explicit value contract — the pattern ^(start|ses_[0-9A-Za-z]{27})$. An agent sends the literal start to begin a new task, or the ses_ ID issued for the task underway, so sessions never split by accident. Calls that omit it are still accepted and treated exactly like start, so requiredness binds only schema-aware clients.
• mcp_session replaces _mcp_instructions as the structured mirror in structuredContent: {session_id?, agent_id?, status?}, with a machine-readable status enum (issued / active / unrecognized) in place of the prose instructions member. Every response state an agent can encounter is pre-announced in the output schema.
• Recovery is explicit. An unrecognized value comes back as mcp_session.status: "unrecognized" plus a leading [session_id unrecognized …] text block, with the recovery path — re-send the ID issued earlier, or start if none was — stated in the schema. No replacement ID is issued in that response.
• Leaner, self-describing copy. The session_id and agent_id descriptions explain the mechanism in terms of what your server does and pre-announce both text-block headers; the two agent_id variants collapse into one, used in both modes. The strings stay byte-identical across all three AgentCat SDKs, pinned by golden tests.

Breaking wire changes

Only for consumers that assert on response internals or advertised schemas — tests, proxies, clients that read structuredContent:

• Mirror key renamed _mcp_instructions → mcp_session; its instructions member is replaced by status.
• The issuance block moved from the last to the first content position, and its headers changed: [session_id issued — see this tool's session_id parameter description] / [session_id unrecognized — see this tool's session_id parameter description].
• session_id and agent_id now appear in each tool's required array, and session_id declares the validation pattern above.

Everything else — argument stripping, handle validation, the agentcat_session_id_source tags, hook mode, redaction, exporters, AgentCatOptions — is unchanged.

Also in this release

• Dependabot now delivers security updates only, with no automated merges (#52).

Install

pip install agentcat

Full changelog: v2.0.2...v2.1.0