microsoft/agent-host-protocol v0.4.0

AHP Swift Package v0.4.0

Repository: microsoft/agent-host-protocol

Tag: v0.4.0

Published: 2026-06-19T18:27:19Z

Prerelease: no

Release notes:

[0.4.0] — 2026-06-19

Implements AHP 0.4.0.

Added

• MessageOrigin struct and MessageKind enum now type Message.origin

(previously an untyped AnyCodable); MessageKind covers user, agent, tool, and systemNotification, adding faithful agent- and tool-initiated origins.

• ConfigPropertySchema.additionalProperties — optional field describing the

schema for object-typed config properties beyond those in properties.

• ChangesetContentChangedAction for full-replacement changeset file

snapshots with optional operations and error details.

• ChangesetOperationStatus.disabled — new case for changeset operations

that are currently unavailable and cannot be invoked.

• ChangesetOperation.group — optional identifier for grouping related

changeset operations together in the UI.

• _meta (meta) field on the per-turn chat actions (chat/turnStarted,

chat/delta, chat/responsePart, chat/reasoning, chat/usage, chat/turnComplete, chat/turnCancelled, chat/error) — optional provider-specific metadata so hosts can carry portable per-event context, such as attributing an event to a specific agent (e.g. a sub-agent acting within the turn).

Changed

• ToolResultSubagentContent.resource is now specified as the spawned worker

chat URI (ahp-chat:/), not a session URI — a tool-spawned sub-agent is a chat. Its doc now describes the correspondence with the worker chat's ChatOrigin.tool record (matching toolCallId), which remains the canonical representation of the spawn relationship.

• BREAKING: SessionStatus is now an OptionSet with a UInt32 rawValue

(was Int), an unsigned 32-bit bitset that preserves combined and unknown forward-compat bits. Combine flags with set-union (∪ / union) and test membership with contains(_:).

• BREAKING: ChangesetOperationTarget's range target now carries a nested

TextRange ({start: {line, character}, end: {line, character}}) instead of a flat {start, end} integer pair.

Added

• SnapshotState.resourceWatch case and matching

MultiHostStateMirror.resourceWatches slot, so applySnapshot(host:snapshot:) can seed an ahp-resource-watch: channel's descriptor (root URI, recursive flag, optional includes/excludes) alongside the existing root / session / terminal / changeset / annotations slots. reset(host:) / reset() clear the new slot.

Fixed

• AnyCodable.encode no longer corrupts NSNumber-backed Int/Double values to Bool/Int. NSNumber is now special-cased before the generic Swift type arms, using CFBooleanGetTypeID() to distinguish boolean from numeric NSNumber instances.
• AnyCodable.encode(to:) now preserves unsigned integers above Int64.max (encoding NSNumber values whose objCType is unsigned via uint64Value instead of the signed int64Value fallback), and the AnyCodable.swift template in scripts/generate-swift.ts reproduces the full encode/equality logic so regenerating the scaffold no longer reintroduces the bug.
• MultiHostClient/host runtime now advertises the generated SUPPORTED_PROTOCOL_VERSIONS on initialize instead of a stale hard-coded "0.2.0".
• Session reducers now apply _meta (meta) updates from every

tool-call-scoped action, not only session/toolCallStart.

Added

• annotationsReducer implemented; annotations conformance fixtures (210–219) now pass.

• AnnotationsUpdatedAction (annotations/updated) — partially updates an

existing annotation's turnId / resource / range / resolved without resending its entries. Handled by the annotations reducer (no-op on unknown id).

• ahp-chat: channel for per-chat conversation state; SessionState.chats[] catalog; SessionState.defaultChat? input-routing hint; ChatOrigin provenance union; createChat / disposeChat commands.
• SessionChatAddedAction, SessionChatRemovedAction, and SessionChatUpdatedAction handling for incremental chat catalog updates.
• ChatSummary.workingDirectory — optional per-chat working directory. Falls back to the session's workingDirectory when absent.
• SessionDefaultChatChangedAction (session/defaultChatChanged) — updates SessionState.defaultChat to steer new input to the designated chat; absent value clears the hint.
• ErrorInfo.meta: [String: AnyCodable]? — optional provider-specific metadata bag on error payloads (serialized as _meta), mirroring the existing meta field on UsageInfo and other protocol types. Clients MAY inspect well-known keys here for richer, localised error UI.
• RootState now exposes an optional _meta property bag (`meta: [String:

AnyCodable]?) for implementation-defined agent-host metadata, such as a well-known hostBuild` key carrying the host's build version/commit/date.

• changesetReducer and resourceWatchReducer — the two state reducers

that were missing from the Swift client are now implemented, mirroring the canonical TypeScript reducers (and the Kotlin/.NET clients). changesetReducer folds changeset/* actions into ChangesetState; resourceWatchReducer treats resourceWatch/changed as a documented event pass-through. The fixture-driven reducer test no longer silently skips the terminal, changeset, and resourceWatch fixture families — they now decode and assert, with the remaining gaps (unknown-discriminant response part; the not-yet-implemented annotations channel) pinned by an explicit drift tripwire.

Changed

• ChatState is now flat — the previous embedded summary has been replaced with inlined resource / title / status / activity / modifiedAt / model / agent / origin / workingDirectory properties. ChatSummary remains as the standalone catalog entry on SessionState.chats.
• ChatSummary.modifiedAt and ChatState.modifiedAt are now ISO 8601 String values instead of Int64/UInt64 milliseconds.

Added

• ChatSummary.interactivity / ChatState.interactivity ("full" | "read-only" | "hidden") indicating how the user can interact with a chat. Absent defaults to "full".

Removed

• SessionChatsChangedAction (replaced by the three discrete chat-catalog actions above).

Fixed

• Encode-fidelity: an unknown StateAction variant no longer re-encodes to

{} (dropping its type discriminant and extra fields); the raw payload is preserved on decode and...