@pi-in-go/pigpen-ahp 0.1.0

package/extensions/ahp/third_party/agent-host-protocol-go/ahptypes/common.go

@@ -0,0 +1,205 @@
+// Package ahptypes contains the wire protocol types for the
+// [Agent Host Protocol] (AHP).
+//
+// Every command, action, notification, and state object defined by the
+// protocol has a Go counterpart here. Structs are tagged for
+// [encoding/json] and use the exact same JSON field names as the wire
+// format. There is no I/O, no goroutines, and no transport code; if you
+// only need to parse or construct AHP messages, this is the only package
+// you need.
+//
+// Most of this package is generated from the canonical TypeScript
+// source-of-truth in types/. Hand-written code lives in common.go and
+// discriminated_unions.go; everything else is rewritten on
+// `npm run generate:go`.
+//
+// # Companion packages
+//
+//   - [github.com/microsoft/agent-host-protocol/clients/go/ahp] — async
+//     client, reducers, and pluggable Transport.
+//   - [github.com/microsoft/agent-host-protocol/clients/go/ahpws] —
+//     WebSocket transport built on [github.com/coder/websocket].
+//
+// # Notes on type mapping
+//
+//   - TypeScript number → Go int64 (the AHP spec defines numbers as
+//     64-bit ints unless a property carries `@format float`, in which
+//     case it's emitted as float64).
+//   - TS unknown / object → [encoding/json.RawMessage] (boxes any JSON).
+//   - TS discriminated unions → concrete wrapper struct (e.g.
+//     [StateAction], [ResponsePart], [ToolCallState]) with a typed
+//     Value field plus custom MarshalJSON/UnmarshalJSON. Unknown
+//     discriminator values surface as a `*XUnknown` variant with the
+//     raw JSON preserved.
+//   - Bitset enums → typed uint32 with named flag constants and Has/Or
+//     helpers; unknown future bits round-trip naturally.
+//   - Required fields are emitted without `,omitempty`. Optional fields
+//     are pointer types with `,omitempty`.
+//
+// [Agent Host Protocol]: https://microsoft.github.io/agent-host-protocol/
+package ahptypes
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+)
+
+// URI is a URI string such as `ahp-root://` or `ahp-session:/<uuid>`.
+//
+// Declared as a defined string type rather than a plain alias so that
+// AHP-typed code can be a little more self-documenting and so future
+// helper methods can hang here without breaking the wire format.
+type URI = string
+
+// RootResourceURI is the well-known channel URI for the root channel.
+//
+// Subscribe to this URI to receive [RootState] snapshots and root-level
+// actions (agents changed, active sessions changed, terminals changed,
+// config changed). Always present on every host.
+const RootResourceURI URI = "ahp-root://"
+
+// JSONObject is a typed alias for an opaque JSON object. Used for
+// `_meta`, `structuredContent`, and other Record<string, unknown>
+// fields where preserving the raw JSON is preferable to forcing a
+// concrete Go type.
+type JSONObject = map[string]json.RawMessage
+
+// AnyValue is an opaque JSON value (the Go counterpart of the
+// TypeScript `unknown` type).
+type AnyValue = json.RawMessage
+
+// PartialChatSummary is the partial equivalent of ChatSummary — every field is optional for delta updates.
+type PartialChatSummary struct {
+	// Chat URI. Ignored by session/chatUpdated reducers; chat identity never changes.
+	Resource *URI `json:"resource,omitempty"`
+	// Chat title
+	Title *string `json:"title,omitempty"`
+	// Current chat status (reuses SessionStatus shape)
+	Status *SessionStatus `json:"status,omitempty"`
+	// Human-readable description of what the chat is currently doing
+	Activity *string `json:"activity,omitempty"`
+	// Last modification timestamp (ISO 8601, e.g. `"2025-03-10T18:42:03.123Z"`)
+	ModifiedAt *string `json:"modifiedAt,omitempty"`
+	// How this chat came into existence
+	Origin *ChatOrigin `json:"origin,omitempty"`
+	// The subset of the session's working directories this chat uses.
+	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
+}
+
+// ─── StringOrMarkdown ────────────────────────────────────────────────────
+
+// StringOrMarkdown is a wire value that may be either a plain JSON
+// string or an object of the form `{"markdown": "..."}`. The wrapper
+// preserves which form was decoded so that re-encoding round-trips
+// faithfully.
+type StringOrMarkdown struct {
+	// Markdown is non-nil iff the value was decoded from the
+	// `{"markdown": "..."}` form.
+	Markdown *string
+
+	// Plain holds the value when decoded from a bare JSON string.
+	// Either Markdown or Plain (but never both) is non-nil after a
+	// successful UnmarshalJSON.
+	Plain *string
+}
+
+// NewStringOrMarkdownPlain returns a [StringOrMarkdown] that encodes
+// as a bare JSON string.
+func NewStringOrMarkdownPlain(s string) StringOrMarkdown {
+	return StringOrMarkdown{Plain: &s}
+}
+
+// NewStringOrMarkdownMarkdown returns a [StringOrMarkdown] that
+// encodes as `{"markdown": s}`.
+func NewStringOrMarkdownMarkdown(s string) StringOrMarkdown {
+	return StringOrMarkdown{Markdown: &s}
+}
+
+// AsText returns the underlying text regardless of which form the
+// value was decoded from. Returns the empty string for the zero value.
+func (s StringOrMarkdown) AsText() string {
+	if s.Plain != nil {
+		return *s.Plain
+	}
+	if s.Markdown != nil {
+		return *s.Markdown
+	}
+	return ""
+}
+
+// MarshalJSON encodes the value back into its original wire form.
+//
+// The zero value encodes as the empty JSON string `""` to match the
+// Rust client's [Default::default] behaviour. Setting both Plain and
+// Markdown is a programming error; the marshaler prefers Plain in
+// that case.
+func (s StringOrMarkdown) MarshalJSON() ([]byte, error) {
+	if s.Plain != nil {
+		return json.Marshal(*s.Plain)
+	}
+	if s.Markdown != nil {
+		return json.Marshal(struct {
+			Markdown string `json:"markdown"`
+		}{*s.Markdown})
+	}
+	return []byte(`""`), nil
+}
+
+// UnmarshalJSON populates the value from either form.
+func (s *StringOrMarkdown) UnmarshalJSON(b []byte) error {
+	*s = StringOrMarkdown{}
+	if len(b) == 0 || string(b) == "null" {
+		return nil
+	}
+	if b[0] == '"' {
+		var v string
+		if err := json.Unmarshal(b, &v); err != nil {
+			return err
+		}
+		s.Plain = &v
+		return nil
+	}
+	var obj struct {
+		Markdown *string `json:"markdown"`
+	}
+	if err := json.Unmarshal(b, &obj); err != nil {
+		return fmt.Errorf("StringOrMarkdown: %w", err)
+	}
+	if obj.Markdown == nil {
+		return errors.New("StringOrMarkdown: object form missing required `markdown` field")
+	}
+	s.Markdown = obj.Markdown
+	return nil
+}
+
+// ─── Discriminated-union helpers ─────────────────────────────────────────
+
+// readDiscriminator parses the value of a top-level discriminator
+// field (`type`, `kind`, `status`, …) from a raw JSON object.
+//
+// Returns the string value, a boolean indicating whether the field
+// was present, and an error if the JSON was malformed.
+func readDiscriminator(raw []byte, field string) (string, bool, error) {
+	var probe map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &probe); err != nil {
+		return "", false, err
+	}
+	v, ok := probe[field]
+	if !ok {
+		return "", false, nil
+	}
+	var s string
+	if err := json.Unmarshal(v, &s); err != nil {
+		return "", false, fmt.Errorf("discriminator %q: %w", field, err)
+	}
+	return s, true, nil
+}
+
+func missingDiscriminatorError(typeName string, field string) error {
+	return fmt.Errorf("%s: missing %q discriminator", typeName, field)
+}
+
+func unknownDiscriminatorError(typeName string, field string, value string) error {
+	return fmt.Errorf("%s: unknown %q discriminator %q", typeName, field, value)
+}

package/extensions/ahp/third_party/agent-host-protocol-go/ahptypes/errors.generated.go

@@ -0,0 +1,65 @@
+// Generated from types/*.ts — do not edit.
+//
+// Regenerate with: npm run generate:go
+
+package ahptypes
+
+// ─── Standard JSON-RPC Error Codes ─────────────────────────────────────────
+
+// Standard JSON-RPC 2.0 error codes.
+const (
+	// ErrorCodeParseError indicates the request body was invalid JSON.
+	ErrorCodeParseError int32 = -32700
+	// ErrorCodeInvalidRequest indicates the payload was not a valid
+	// JSON-RPC request.
+	ErrorCodeInvalidRequest int32 = -32600
+	// ErrorCodeMethodNotFound indicates the requested method does not
+	// exist on the server.
+	ErrorCodeMethodNotFound int32 = -32601
+	// ErrorCodeInvalidParams indicates the method parameters did not
+	// match the declared schema.
+	ErrorCodeInvalidParams int32 = -32602
+	// ErrorCodeInternalError indicates an unspecified server failure.
+	ErrorCodeInternalError int32 = -32603
+)
+
+// AHP application-specific error codes (above the JSON-RPC reserved
+// range).
+const (
+	ErrorCodeSessionNotFound            int32 = -32001
+	ErrorCodeProviderNotFound           int32 = -32002
+	ErrorCodeSessionAlreadyExists       int32 = -32003
+	ErrorCodeTurnInProgress             int32 = -32004
+	ErrorCodeUnsupportedProtocolVersion int32 = -32005
+	// -32006 is intentionally reserved and unassigned.
+	ErrorCodeAuthRequired     int32 = -32007
+	ErrorCodeNotFound         int32 = -32008
+	ErrorCodePermissionDenied int32 = -32009
+	ErrorCodeAlreadyExists    int32 = -32010
+)
+
+// AhpErrorCode is the type alias used by AHP application error codes.
+type AhpErrorCode = int32
+
+// JsonRpcErrorCode is the type alias used by standard JSON-RPC codes.
+type JsonRpcErrorCode = int32
+
+// ─── Error Detail Payloads ────────────────────────────────────────────────
+
+// AuthRequiredErrorData is the detail payload of an AuthRequired
+// (-32007) error.
+type AuthRequiredErrorData struct {
+	Resources []ProtectedResourceMetadata `json:"resources"`
+}
+
+// PermissionDeniedErrorData is the detail payload of a
+// PermissionDenied (-32009) error.
+type PermissionDeniedErrorData struct {
+	Request *ResourceRequestParams `json:"request,omitempty"`
+}
+
+// UnsupportedProtocolVersionErrorData is the detail payload of an
+// UnsupportedProtocolVersion (-32005) error.
+type UnsupportedProtocolVersionErrorData struct {
+	SupportedVersions []string `json:"supportedVersions"`
+}

package/extensions/ahp/third_party/agent-host-protocol-go/ahptypes/messages.generated.go

@@ -0,0 +1,138 @@
+// Generated from types/*.ts — do not edit.
+//
+// Regenerate with: npm run generate:go
+
+package ahptypes
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// ─── JSON-RPC Envelope ────────────────────────────────────────────────────
+
+// JsonRpcVersion is the sole allowed value of the `jsonrpc` field
+// (`"2.0"`).
+type JsonRpcVersion string
+
+// JsonRpcV2 is the canonical `"2.0"` JSON-RPC version literal.
+const JsonRpcV2 JsonRpcVersion = "2.0"
+
+// JsonRpcRequest is a JSON-RPC 2.0 request (method + id).
+type JsonRpcRequest struct {
+	JsonRpc JsonRpcVersion  `json:"jsonrpc"`
+	ID      uint64          `json:"id"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+}
+
+// JsonRpcSuccessResponse is a JSON-RPC 2.0 success response.
+type JsonRpcSuccessResponse struct {
+	JsonRpc JsonRpcVersion  `json:"jsonrpc"`
+	ID      uint64          `json:"id"`
+	Result  json.RawMessage `json:"result"`
+}
+
+// JsonRpcErrorResponse is a JSON-RPC 2.0 error response.
+type JsonRpcErrorResponse struct {
+	JsonRpc JsonRpcVersion `json:"jsonrpc"`
+	ID      uint64         `json:"id"`
+	Error   JsonRpcError   `json:"error"`
+}
+
+// JsonRpcError is the standard JSON-RPC 2.0 error object.
+type JsonRpcError struct {
+	Code    int32           `json:"code"`
+	Message string          `json:"message"`
+	Data    json.RawMessage `json:"data,omitempty"`
+}
+
+// Error implements the standard error interface.
+func (e *JsonRpcError) Error() string {
+	return fmt.Sprintf("jsonrpc error %d: %s", e.Code, e.Message)
+}
+
+// JsonRpcNotification is a JSON-RPC 2.0 notification (method, no id).
+type JsonRpcNotification struct {
+	JsonRpc JsonRpcVersion  `json:"jsonrpc"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+}
+
+// JsonRpcMessage is a discriminated union over the four JSON-RPC
+// message shapes. Use [DecodeJsonRpcMessage] to parse an inbound frame
+// into the correct variant.
+type JsonRpcMessage struct {
+	Request         *JsonRpcRequest
+	SuccessResponse *JsonRpcSuccessResponse
+	ErrorResponse   *JsonRpcErrorResponse
+	Notification    *JsonRpcNotification
+}
+
+// MarshalJSON encodes whichever variant is populated.
+func (m JsonRpcMessage) MarshalJSON() ([]byte, error) {
+	switch {
+	case m.Request != nil:
+		return json.Marshal(m.Request)
+	case m.SuccessResponse != nil:
+		return json.Marshal(m.SuccessResponse)
+	case m.ErrorResponse != nil:
+		return json.Marshal(m.ErrorResponse)
+	case m.Notification != nil:
+		return json.Marshal(m.Notification)
+	default:
+		return []byte("null"), nil
+	}
+}
+
+// UnmarshalJSON inspects the raw object's shape to pick a variant.
+//
+// JSON-RPC 2.0's shape rules:
+//   - request:        has `id` and `method`
+//   - notification:   has `method` but no `id`
+//   - success-resp:   has `id` and `result` (no `error`)
+//   - error-resp:     has `id` and `error` (no `result`)
+func (m *JsonRpcMessage) UnmarshalJSON(data []byte) error {
+	*m = JsonRpcMessage{}
+	var probe map[string]json.RawMessage
+	if err := json.Unmarshal(data, &probe); err != nil {
+		return err
+	}
+	_, hasMethod := probe["method"]
+	_, hasID := probe["id"]
+	_, hasResult := probe["result"]
+	_, hasError := probe["error"]
+	switch {
+	case hasMethod && hasID:
+		var v JsonRpcRequest
+		if err := json.Unmarshal(data, &v); err != nil {
+			return err
+		}
+		m.Request = &v
+	case hasMethod:
+		var v JsonRpcNotification
+		if err := json.Unmarshal(data, &v); err != nil {
+			return err
+		}
+		m.Notification = &v
+	case hasError:
+		var v JsonRpcErrorResponse
+		if err := json.Unmarshal(data, &v); err != nil {
+			return err
+		}
+		m.ErrorResponse = &v
+	case hasResult:
+		var v JsonRpcSuccessResponse
+		if err := json.Unmarshal(data, &v); err != nil {
+			return err
+		}
+		m.SuccessResponse = &v
+	default:
+		return fmt.Errorf("ahptypes: JSON-RPC message has no method/result/error")
+	}
+	return nil
+}
+
+// ActionNotificationParams is the params shape of the server → client
+// `action` JSON-RPC method.
+type ActionNotificationParams = ActionEnvelope

package/extensions/ahp/third_party/agent-host-protocol-go/ahptypes/notifications.generated.go

@@ -0,0 +1,264 @@
+// Generated from types/*.ts — do not edit.
+//
+// Regenerate with: npm run generate:go
+
+package ahptypes
+
+import (
+	"encoding/json"
+)
+
+// Reference the encoding/json import to keep gofmt -d from
+// stripping it when a generated file has no struct that mentions
+// json.RawMessage directly (rare but possible). Compiled out.
+var _ = json.RawMessage(nil)
+
+// ─── Enums ────────────────────────────────────────────────────────────
+
+// Reason why authentication is required.
+type AuthRequiredReason string
+
+const (
+	// The client has not yet authenticated for the resource
+	AuthRequiredReasonRequired AuthRequiredReason = "required"
+	// A previously valid token has expired or been revoked. The client must
+	// acquire or renew the credential rather than replaying the challenged token.
+	AuthRequiredReasonExpired AuthRequiredReason = "expired"
+)
+
+// ─── Notification Payloads ────────────────────────────────────────────
+
+// Broadcast to all clients subscribed to the root channel when a new session
+// is created.
+type SessionAddedParams struct {
+	// Channel URI this notification belongs to (the root channel)
+	Channel URI `json:"channel"`
+	// Summary of the new session
+	Summary SessionSummary `json:"summary"`
+}
+
+// Broadcast to all clients subscribed to the root channel when a session is
+// disposed.
+type SessionRemovedParams struct {
+	// Channel URI this notification belongs to (the root channel)
+	Channel URI `json:"channel"`
+	// URI of the removed session
+	Session URI `json:"session"`
+}
+
+// Broadcast to all clients subscribed to the root channel when an existing
+// session's summary changes (title, status, `modifiedAt`, model, working
+// directory, read/done state, or diff statistics).
+//
+// This notification lets clients that maintain a cached session list — for
+// example, the result of a previous `listSessions()` call — stay in sync with
+// in-flight sessions without having to subscribe to every session URI
+// individually. It is complementary to, not a replacement for,
+// `root/sessionAdded` and `root/sessionRemoved`: those signal lifecycle
+// (creation/disposal), while this signals summary-level mutations on an
+// already-known session.
+//
+// Semantics:
+//
+//   - Only fields present in `changes` have new values; omitted fields are
+//     unchanged on the client's cached summary.
+//   - Identity fields (`resource`, `provider`, `createdAt`) never change and
+//     are not carried.
+//   - Like all protocol notifications, this is ephemeral: it is **not**
+//     replayed on reconnect. On reconnect, clients should re-fetch the full
+//     catalog via `listSessions()` as usual.
+//   - The server SHOULD emit this notification whenever any mutable field on
+//     {@link SessionSummary | `SessionSummary`} changes for a session the
+//     server has surfaced via `listSessions()` or `root/sessionAdded`.
+//     Servers MAY coalesce or debounce updates for noisy fields (for example,
+//     `modifiedAt` bumps while a turn is streaming) at their discretion.
+//   - Clients that have no cached entry for `session` MAY ignore the
+//     notification; it is not a substitute for `root/sessionAdded`.
+type SessionSummaryChangedParams struct {
+	// Channel URI this notification belongs to (the root channel)
+	Channel URI `json:"channel"`
+	// URI of the session whose summary changed
+	Session URI `json:"session"`
+	// Mutable summary fields that changed; omitted fields are unchanged.
+	//
+	// Identity fields (`resource`, `provider`, `createdAt`) never change and
+	// MUST be omitted by senders; receivers SHOULD ignore them if present.
+	Changes PartialSessionSummary `json:"changes"`
+}
+
+// Generic progress notification for a long-running operation.
+//
+// A client opts in to progress for a request by including a `progressToken` in
+// that request (today: the `progressToken` field on `createSession`). If the
+// server does long-running work to service the request — e.g. lazily
+// downloading an agent's native SDK the first time a session of that provider
+// is materialized — it emits `progress` notifications carrying the same token.
+//
+// The notification is operation-agnostic: it says nothing about *what* is
+// progressing. The client correlates `progressToken` back to the request it
+// originated from (and thus the UI surface awaiting it) and renders its own
+// localized indicator. The same channel serves any future long-running
+// operation without a new method.
+//
+// Semantics:
+//
+//   - `progress` is monotonically non-decreasing for a given `progressToken`.
+//   - `total` is present only when the server knows the magnitude up front
+//     (e.g. a `Content-Length`); when absent the client SHOULD show an
+//     indeterminate indicator.
+//   - The operation is complete when `progress === total`. The server MUST emit a
+//     final frame satisfying `progress === total`; when the total was never
+//     known, it sets `total` to the final `progress` on that frame. No further
+//     frames reference the token afterwards.
+//   - The server MAY emit no progress at all (e.g. the work was already done);
+//     the client then never shows an indicator.
+//   - Like all notifications this is ephemeral and is **not** replayed on
+//     reconnect. A client that never receives the terminal frame SHOULD expire
+//     the indicator after an idle timeout.
+type ProgressParams struct {
+	// Channel URI this notification belongs to (the root channel).
+	Channel URI `json:"channel"`
+	// Echoes the `progressToken` the client supplied on the originating request
+	// (e.g. the `progressToken` field of `createSession`), correlating this frame
+	// to that call. Unique across the client's active requests.
+	ProgressToken string `json:"progressToken"`
+	// Progress so far, in operation-defined units (e.g. bytes received).
+	// Monotonically non-decreasing for a given `progressToken`.
+	Progress int64 `json:"progress"`
+	// Total when known up front (e.g. from a `Content-Length`); omitted ⇒
+	// indeterminate. The operation is complete once `progress === total`.
+	Total *int64 `json:"total,omitempty"`
+	// Optional human-readable progress message. The client owns its own
+	// (localized) presentation derived from the originating request; generic
+	// clients that don't track the token MAY display this instead.
+	Message *string `json:"message,omitempty"`
+}
+
+// Sent by the server when a protected resource requires (re-)authentication.
+//
+// This notification MAY be associated with any channel — for example, an
+// agent advertised on the root channel, or a per-session resource. The
+// `channel` field identifies the subscription the auth requirement belongs
+// to; the `resource` field carries the complete OAuth protected resource
+// metadata (per RFC 9728).
+//
+// Clients should obtain or renew the credential and push the resulting token
+// via the `authenticate` command. When `reason` is `expired`, clients MUST NOT
+// blindly replay the challenged token.
+type AuthRequiredParams struct {
+	// Channel URI this notification belongs to
+	Channel URI `json:"channel"`
+	// Complete RFC 9728 metadata for the protected resource that requires authentication
+	Resource ProtectedResourceMetadata `json:"resource"`
+	// Why authentication is required
+	Reason *AuthRequiredReason `json:"reason,omitempty"`
+}
+
+// Delivers a batch of OTLP log records to a client subscribed to the host's
+// logs channel (advertised on `TelemetryCapabilities.logs`).
+//
+// The `payload` field is an OTLP/JSON `ExportLogsServiceRequest` value
+// verbatim — i.e. an object of shape `{ resourceLogs: ResourceLogs[] }` as
+// defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto).
+// AHP does not redeclare the OTLP type system; clients SHOULD use an
+// OpenTelemetry SDK or schema to parse it.
+//
+// Like all stateless-channel notifications, this is ephemeral: it is not
+// replayed on reconnect. Subscribers receive only batches emitted after
+// their `subscribe` succeeds.
+type OtlpExportLogsParams struct {
+	// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.logs`).
+	Channel URI `json:"channel"`
+	// OTLP/JSON `ExportLogsServiceRequest` value. The top-level field is
+	// `resourceLogs: ResourceLogs[]`; nested shapes are defined by
+	// opentelemetry-proto and are not redeclared here.
+	Payload map[string]json.RawMessage `json:"payload"`
+}
+
+// Delivers a batch of OTLP spans to a client subscribed to the host's
+// traces channel (advertised on `TelemetryCapabilities.traces`).
+//
+// The `payload` field is an OTLP/JSON `ExportTraceServiceRequest` value
+// verbatim — i.e. an object of shape `{ resourceSpans: ResourceSpans[] }`
+// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto).
+type OtlpExportTracesParams struct {
+	// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.traces`).
+	Channel URI `json:"channel"`
+	// OTLP/JSON `ExportTraceServiceRequest` value. The top-level field is
+	// `resourceSpans: ResourceSpans[]`; nested shapes are defined by
+	// opentelemetry-proto and are not redeclared here.
+	Payload map[string]json.RawMessage `json:"payload"`
+}
+
+// Delivers a batch of OTLP metric data points to a client subscribed to
+// the host's metrics channel (advertised on `TelemetryCapabilities.metrics`).
+//
+// The `payload` field is an OTLP/JSON `ExportMetricsServiceRequest` value
+// verbatim — i.e. an object of shape `{ resourceMetrics: ResourceMetrics[] }`
+// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/metrics/v1/metrics_service.proto).
+type OtlpExportMetricsParams struct {
+	// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.metrics`).
+	Channel URI `json:"channel"`
+	// OTLP/JSON `ExportMetricsServiceRequest` value. The top-level field is
+	// `resourceMetrics: ResourceMetrics[]`; nested shapes are defined by
+	// opentelemetry-proto and are not redeclared here.
+	Payload map[string]json.RawMessage `json:"payload"`
+}
+
+// ─── Partial Summaries ────────────────────────────────────────────────
+
+// PartialSessionSummary is the partial equivalent of SessionSummary — every field is optional for delta updates.
+type PartialSessionSummary struct {
+	// Agent provider ID
+	Provider *string `json:"provider,omitempty"`
+	// Session title
+	Title *string `json:"title,omitempty"`
+	// Current session status
+	Status *SessionStatus `json:"status,omitempty"`
+	// Human-readable description of what the session is currently doing
+	Activity *string `json:"activity,omitempty"`
+	// Durable {@link AutomationSessionOrigin}, when an automation run created this session.
+	Origin *SessionOrigin `json:"origin,omitempty"`
+	// Server-owned project for this session
+	Project *ProjectInfo `json:"project,omitempty"`
+	// The working directories the session's agent has tool access to, as
+	// maintained by working-directory actions. Directories are equal peers except
+	// when the agent advertises
+	// {@link MultipleWorkingDirectoriesCapability.immutablePrimary} without
+	// {@link MultipleWorkingDirectoriesCapability.primaryReplacement} (the first
+	// entry is then a fixed process root), or advertises `primaryReplacement`
+	// (the first entry is a protected, replaceable primary slot). Individual chats
+	// MAY restrict to a subset via
+	// {@link ChatSummary.workingDirectories | their own `workingDirectories`}; a
+	// chat that sets none operates against this full set.
+	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
+	// Lightweight summary of this session's inline annotations channel
+	// (`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render
+	// annotation / entry counts without subscribing. Absent when the session
+	// does not expose an annotations channel.
+	Annotations *AnnotationsSummary `json:"annotations,omitempty"`
+	// Session URI
+	Resource *URI `json:"resource,omitempty"`
+	// Creation timestamp (ISO 8601, e.g. `"2025-03-10T18:42:03.123Z"`)
+	CreatedAt *string `json:"createdAt,omitempty"`
+	// Last modification timestamp (ISO 8601, e.g. `"2025-03-10T18:42:03.123Z"`)
+	ModifiedAt *string `json:"modifiedAt,omitempty"`
+	// Aggregate summary of file changes associated with this session. Servers
+	// may populate this to give clients a quick at-a-glance view of the
+	// session's footprint (e.g., for list rendering) without requiring the
+	// client to subscribe to a changeset.
+	Changes *ChangesSummary `json:"changes,omitempty"`
+	// Lightweight server-defined metadata clients may use for the session
+	// presentation. The protocol does not interpret these values; producers
+	// SHOULD keep the payload small because summaries appear in session lists
+	// and session notifications.
+	Meta map[string]json.RawMessage `json:"_meta,omitempty"`
+	// Lightweight ordered chat catalog for session-list presentation.
+	//
+	// This intentionally omits volatile chat state such as status and activity,
+	// while retaining interactivity so generic clients can hide chats or present
+	// them as read-only without subscribing to the session channel.
+	Chats []SessionChatSummary `json:"chats,omitempty"`
+	// Chat that receives input when no specific chat is selected.
+	DefaultChat *URI `json:"defaultChat,omitempty"`
+}