Add typed repository source inputs and session metadata

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs

@@ -462,7 +462,10 @@ public sealed record SubscribeResult
 ///
 /// After creation, the client should subscribe to the session URI to receive state
 /// updates. The server also broadcasts a `root/sessionAdded` notification to all
-/// clients.</summary>
+/// clients.
+///
+/// Repository preparation MUST finish before `session/ready` or executing turns.
+/// Clients recover the outcome from session state, not progress notifications.</summary>
 public sealed record CreateSessionParams
 {
     /// <summary>Session URI (client-chosen, e.g. `ahp-session:/&lt;uuid&gt;`)</summary>
@@ -490,12 +493,24 @@ public sealed record CreateSessionParams
     /// {@link AgentCapabilities.multipleWorkingDirectories}; a server without that
     /// capability treats only the first entry as the session's working directory
     /// and ignores the rest. Dispatch working-directory actions to change the set
-    /// after the session has started.</summary>
+    /// after the session has started.
+    ///
+    /// A non-empty list and `repositorySource` are mutually exclusive.
+    /// A repository URI identifies the source, not a working-directory URI; one
+    /// source may produce multiple directories.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<string>? WorkingDirectories { get; init; }
 
-    /// <summary>Agent-specific configuration values collected via `resolveSessionConfig`.
-    /// Keys and values correspond to the schema returned by the server.</summary>
+    /// <summary>Credential-free source to prepare; requires the agent's repositorySource capability.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; init; }
+
+    /// <summary>Requested branch, tag, or commit; requires a source and the capability's revision option.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; init; }
+
+    /// <summary>Session configuration values collected via `resolveSessionConfig`.
+    /// Keys and values follow the advertised {@link SessionConfigSchema}.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public Dictionary<string, JsonElement>? Config { get; init; }
 
@@ -524,7 +539,10 @@ public sealed record CreateSessionParams
 
 /// <summary>Disposes a session and cleans up server-side resources.
 ///
-/// The server broadcasts a `root/sessionRemoved` notification to all clients.</summary>
+/// The server broadcasts a `root/sessionRemoved` notification to all clients.
+/// Disposal MUST NOT erase a shared checkout or uncommitted user changes.
+/// Repository cleanup remains host-owned; ending a client's wait or subscription
+/// does not grant permission to delete repository data.</summary>
 public sealed record DisposeSessionParams
 {
     /// <summary>Channel URI this command targets.</summary>
@@ -1346,7 +1364,10 @@ public sealed record DisposeTerminalParams
 /// The client calls this command whenever the user changes a significant input
 /// (e.g. picks a working directory, toggles a property). Each response returns
 /// the full current property set (not a delta). The returned `values` contain
-/// server-resolved defaults to pass to `createSession`.</summary>
+/// server-resolved defaults to pass to `createSession`.
+///
+/// This command MUST NOT clone or prepare a repository. Repository context
+/// requires the agent's `repositorySource` capability.</summary>
 public sealed record ResolveSessionConfigParams
 {
     public required string Channel { get; init; }
@@ -1365,7 +1386,15 @@ public sealed record ResolveSessionConfigParams
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? WorkingDirectory { get; init; }
 
-    /// <summary>Current user-filled configuration values</summary>
+    /// <summary>Credential-free source context; not a working-directory URI.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; init; }
+
+    /// <summary>Requested revision; requires a source and the capability's revision option.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; init; }
+
+    /// <summary>Current user-filled configuration values; see {@link SessionConfigSchema}.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public Dictionary<string, JsonElement>? Config { get; init; }
 }
@@ -1403,6 +1432,14 @@ public sealed record SessionConfigCompletionsParams
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? WorkingDirectory { get; init; }
 
+    /// <summary>Repository context for configuration completions; this MUST NOT prepare a checkout.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; init; }
+
+    /// <summary>Requested revision; requires a source and the capability's revision option.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; init; }
+
     /// <summary>Current user-filled configuration values (provides context for the query)</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public Dictionary<string, JsonElement>? Config { get; init; }

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/JsonSerializerContext.generated.cs

@@ -264,6 +264,7 @@ namespace Microsoft.AgentHostProtocol;
 [JsonSerializable(typeof(ReconnectResult))]
 [JsonSerializable(typeof(ReconnectResultType))]
 [JsonSerializable(typeof(ReconnectSnapshotResult))]
+[JsonSerializable(typeof(RepositorySourceCapability))]
 [JsonSerializable(typeof(ResolveSessionConfigParams))]
 [JsonSerializable(typeof(ResolveSessionConfigResult))]
 [JsonSerializable(typeof(ResourceChange))]

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Notifications.generated.cs

@@ -117,7 +117,9 @@ public sealed record SessionSummaryChangedParams
 ///   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.</summary>
+///   the indicator after an idle timeout.
+/// - Completion of reported work does not establish session readiness.
+///   Observe session lifecycle state for the durable outcome.</summary>
 public sealed record ProgressParams
 {
     /// <summary>Channel URI this notification belongs to (the root channel).</summary>
@@ -267,6 +269,14 @@ public sealed record PartialSessionSummary
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<string>? WorkingDirectories { get; init; }
 
+    /// <summary>Immutable requested source, separate from the host-resolved working directories.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; init; }
+
+    /// <summary>Immutable requested revision, not the checkout's current HEAD.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; init; }
+
     /// <summary>Lightweight summary of this session's inline annotations channel
     /// (`ahp-session:/&lt;uuid&gt;/annotations`). Surfaced so badge UI can render
     /// annotation / entry counts without subscribing. Absent when the session

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/State.generated.cs

@@ -861,6 +861,10 @@ public sealed record AgentInfo
 /// per-capability options.</summary>
 public sealed record AgentCapabilities
 {
+    /// <summary>The host accepts typed repository inputs for session creation and configuration queries.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public RepositorySourceCapability? RepositorySource { get; init; }
+
     /// <summary>The agent can host more than one concurrent chat per session. When absent,
     /// clients MUST NOT call `createChat` to open chats beyond the default one the
     /// session starts with. An empty object `{}` advertises multi-chat without
@@ -940,6 +944,14 @@ public sealed record MultipleWorkingDirectoriesCapability
     public bool? PrimaryReplacement { get; init; }
 }
 
+/// <summary>Options for repository-backed session creation.</summary>
+public sealed record RepositorySourceCapability
+{
+    /// <summary>When true, clients may supply an explicit repositoryRevision.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public bool? Revision { get; init; }
+}
+
 public sealed record SessionModelInfo
 {
     /// <summary>Model identifier</summary>
@@ -1547,6 +1559,14 @@ public sealed class SessionState
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<string>? WorkingDirectories { get; set; }
 
+    /// <summary>Immutable requested source, separate from the host-resolved working directories.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; set; }
+
+    /// <summary>Immutable requested revision, not the checkout's current HEAD.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; set; }
+
     /// <summary>Lightweight summary of this session's inline annotations channel
     /// (`ahp-session:/&lt;uuid&gt;/annotations`). Surfaced so badge UI can render
     /// annotation / entry counts without subscribing. Absent when the session
@@ -1586,7 +1606,7 @@ public sealed class SessionState
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? DefaultChat { get; set; }
 
-    /// <summary>Session configuration schema and current values</summary>
+    /// <summary>Provider-specific session configuration schema and current values.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public SessionConfigState? Config { get; set; }
 
@@ -1882,6 +1902,14 @@ public sealed class SessionSummary
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<string>? WorkingDirectories { get; set; }
 
+    /// <summary>Immutable requested source, separate from the host-resolved working directories.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositorySource { get; set; }
+
+    /// <summary>Immutable requested revision, not the checkout's current HEAD.</summary>
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? RepositoryRevision { get; set; }
+
     /// <summary>Lightweight summary of this session's inline annotations channel
     /// (`ahp-session:/&lt;uuid&gt;/annotations`). Surfaced so badge UI can render
     /// annotation / entry counts without subscribing. Absent when the session

clients/go/ahptypes/commands.generated.go

@@ -375,6 +375,9 @@ type SubscribeResult struct {
 // After creation, the client should subscribe to the session URI to receive state
 // updates. The server also broadcasts a `root/sessionAdded` notification to all
 // clients.
+//
+// Repository preparation MUST finish before `session/ready` or executing turns.
+// Clients recover the outcome from session state, not progress notifications.
 type CreateSessionParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -396,9 +399,17 @@ type CreateSessionParams struct {
 	// capability treats only the first entry as the session's working directory
 	// and ignores the rest. Dispatch working-directory actions to change the set
 	// after the session has started.
+	//
+	// A non-empty list and `repositorySource` are mutually exclusive.
+	// A repository URI identifies the source, not a working-directory URI; one
+	// source may produce multiple directories.
 	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
-	// Agent-specific configuration values collected via `resolveSessionConfig`.
-	// Keys and values correspond to the schema returned by the server.
+	// Credential-free source to prepare; requires the agent's repositorySource capability.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Requested branch, tag, or commit; requires a source and the capability's revision option.
+	RepositoryRevision *string `json:"repositoryRevision,omitempty"`
+	// Session configuration values collected via `resolveSessionConfig`.
+	// Keys and values follow the advertised {@link SessionConfigSchema}.
 	Config map[string]json.RawMessage `json:"config,omitempty"`
 	// Eagerly claim an active client role for the new session.
 	//
@@ -423,6 +434,9 @@ type CreateSessionParams struct {
 // Disposes a session and cleans up server-side resources.
 //
 // The server broadcasts a `root/sessionRemoved` notification to all clients.
+// Disposal MUST NOT erase a shared checkout or uncommitted user changes.
+// Repository cleanup remains host-owned; ending a client's wait or subscription
+// does not grant permission to delete repository data.
 type DisposeSessionParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -1070,6 +1084,9 @@ type DisposeTerminalParams struct {
 // (e.g. picks a working directory, toggles a property). Each response returns
 // the full current property set (not a delta). The returned `values` contain
 // server-resolved defaults to pass to `createSession`.
+//
+// This command MUST NOT clone or prepare a repository. Repository context
+// requires the agent's `repositorySource` capability.
 type ResolveSessionConfigParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -1080,7 +1097,11 @@ type ResolveSessionConfigParams struct {
 	Provider *string `json:"provider,omitempty"`
 	// Working directory for the session
 	WorkingDirectory *URI `json:"workingDirectory,omitempty"`
-	// Current user-filled configuration values
+	// Credential-free source context; not a working-directory URI.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Requested revision; requires a source and the capability's revision option.
+	RepositoryRevision *string `json:"repositoryRevision,omitempty"`
+	// Current user-filled configuration values; see {@link SessionConfigSchema}.
 	Config map[string]json.RawMessage `json:"config,omitempty"`
 }
 
@@ -1107,6 +1128,10 @@ type SessionConfigCompletionsParams struct {
 	Provider *string `json:"provider,omitempty"`
 	// Working directory for the session
 	WorkingDirectory *URI `json:"workingDirectory,omitempty"`
+	// Repository context for configuration completions; this MUST NOT prepare a checkout.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Requested revision; requires a source and the capability's revision option.
+	RepositoryRevision *string `json:"repositoryRevision,omitempty"`
 	// Current user-filled configuration values (provides context for the query)
 	Config map[string]json.RawMessage `json:"config,omitempty"`
 	// Property id from the schema to query values for

clients/go/ahptypes/notifications.generated.go

@@ -115,6 +115,8 @@ type SessionSummaryChangedParams struct {
 //   - 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.
+//   - Completion of reported work does not establish session readiness.
+//     Observe session lifecycle state for the durable outcome.
 type ProgressParams struct {
 	// Channel URI this notification belongs to (the root channel).
 	Channel URI `json:"channel"`
@@ -232,6 +234,10 @@ type PartialSessionSummary struct {
 	// {@link ChatSummary.workingDirectories | their own `workingDirectories`}; a
 	// chat that sets none operates against this full set.
 	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
+	// Immutable requested source, separate from the host-resolved working directories.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Immutable requested revision, not the checkout's current HEAD.
+	RepositoryRevision *string `json:"repositoryRevision,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

clients/go/ahptypes/state.generated.go

@@ -676,6 +676,8 @@ type AgentInfo struct {
 // corresponding client commands MUST NOT be used. Sub-fields carry
 // per-capability options.
 type AgentCapabilities struct {
+	// The host accepts typed repository inputs for session creation and configuration queries.
+	RepositorySource *RepositorySourceCapability `json:"repositorySource,omitempty"`
 	// The agent can host more than one concurrent chat per session. When absent,
 	// clients MUST NOT call `createChat` to open chats beyond the default one the
 	// session starts with. An empty object `{}` advertises multi-chat without
@@ -744,6 +746,12 @@ type MultipleWorkingDirectoriesCapability struct {
 	PrimaryReplacement *bool `json:"primaryReplacement,omitempty"`
 }
 
+// Options for repository-backed session creation.
+type RepositorySourceCapability struct {
+	// When true, clients may supply an explicit repositoryRevision.
+	Revision *bool `json:"revision,omitempty"`
+}
+
 type SessionModelInfo struct {
 	// Model identifier
 	Id string `json:"id"`
@@ -877,6 +885,10 @@ type SessionState struct {
 	// {@link ChatSummary.workingDirectories | their own `workingDirectories`}; a
 	// chat that sets none operates against this full set.
 	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
+	// Immutable requested source, separate from the host-resolved working directories.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Immutable requested revision, not the checkout's current HEAD.
+	RepositoryRevision *string `json:"repositoryRevision,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
@@ -905,7 +917,7 @@ type SessionState struct {
 	// marker — chats remain equal peers at the protocol level. Hosts MAY change
 	// this over the session's lifetime.
 	DefaultChat *URI `json:"defaultChat,omitempty"`
-	// Session configuration schema and current values
+	// Provider-specific session configuration schema and current values.
 	Config *SessionConfigState `json:"config,omitempty"`
 	// Top-level customizations active in this session.
 	//
@@ -1153,6 +1165,10 @@ type SessionSummary struct {
 	// {@link ChatSummary.workingDirectories | their own `workingDirectories`}; a
 	// chat that sets none operates against this full set.
 	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
+	// Immutable requested source, separate from the host-resolved working directories.
+	RepositorySource *URI `json:"repositorySource,omitempty"`
+	// Immutable requested revision, not the checkout's current HEAD.
+	RepositoryRevision *string `json:"repositoryRevision,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