diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f5adb25..b418fe7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -140,6 +140,8 @@ Nightly builds of `master` are on ### 🐛 Fixes +- **IntelliSense documents declared units, defaults and family roles.** Documentation inferred only + from server implementation is removed; SDK types and runtime behavior are unchanged. - **Generated XML summaries use grammatical prose.** Articles and brand spellings are corrected, digits stay attached to their words, and members named `Value` read "Gets the value." - **A background-service start failure no longer carries part of the PTY handoff ticket.** The diff --git a/docs/architecture/protocol-and-generation.md b/docs/architecture/protocol-and-generation.md index 073e650f..ee13c4a5 100644 --- a/docs/architecture/protocol-and-generation.md +++ b/docs/architecture/protocol-and-generation.md @@ -157,7 +157,12 @@ Curation may: unambiguous wire role (an event, its exclusive payload, an operation's exclusive body, response or query record, an error of the error spine); a record with two roles keeps the plain placeholder. A row whose type or member is gone, a duplicate, or an empty summary or reason fails - generation; + generation. A documentation-only `descriptions` row may state a unit, sentinel, default or format + only when upstream declares it explicitly; every row cites those declarations in a required + `sources` list (each a `packages/path:line` location and a verbatim excerpt) that the curation + validator requires and a Tools test proves against the pinned upstream tree, and facts inferred + only from implementation are reported upstream instead and never change protocol semantics + (ADR-0013); - place a model in a slice where its name carries no family prefix, through a reason-bearing `modelOwners` row; a family's prefixes are its name, its singular, its group key and the group's `prefixAliases`, and a model with no prefix and no row fails generation. A diff --git a/src/OpenCode.Sdk/Agents/AgentsClient.cs b/src/OpenCode.Sdk/Agents/AgentsClient.cs index e31c430c..64284cc2 100644 --- a/src/OpenCode.Sdk/Agents/AgentsClient.cs +++ b/src/OpenCode.Sdk/Agents/AgentsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'AgentsClient' collection client. +/// Lists registered agents and retrieves an agent by identifier. /// public class AgentsClient { diff --git a/src/OpenCode.Sdk/Commands/CommandsClient.cs b/src/OpenCode.Sdk/Commands/CommandsClient.cs index 980bef1d..ea9cee23 100644 --- a/src/OpenCode.Sdk/Commands/CommandsClient.cs +++ b/src/OpenCode.Sdk/Commands/CommandsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'CommandsClient' collection client. +/// Experimental command routes. /// public class CommandsClient { diff --git a/src/OpenCode.Sdk/Config/ConfigClient.cs b/src/OpenCode.Sdk/Config/ConfigClient.cs index 174eb068..276d5aeb 100644 --- a/src/OpenCode.Sdk/Config/ConfigClient.cs +++ b/src/OpenCode.Sdk/Config/ConfigClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'ConfigClient' collection client. +/// Reads the location's configuration documents and lists shells available for terminal and agent execution. /// public class ConfigClient { diff --git a/src/OpenCode.Sdk/Config/Models/ConfigInfoExperimental.cs b/src/OpenCode.Sdk/Config/Models/ConfigInfoExperimental.cs index cdd3ba2f..2548833e 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigInfoExperimental.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigInfoExperimental.cs @@ -9,14 +9,14 @@ namespace OpenCode.Sdk.Models; public sealed record ConfigInfoExperimental { /// - /// Gets the portable shell scanner value. + /// Enable the experimental portable shell permission scanner. Defaults to false. /// [JsonPropertyName("portable_shell_scanner")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public bool? PortableShellScanner { get; init; } /// - /// Gets the subagent depth value. + /// Maximum subagent nesting depth. Defaults to 1. /// [JsonPropertyName("subagent_depth")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Config/Models/ConfigInfoMcpTimeout.cs b/src/OpenCode.Sdk/Config/Models/ConfigInfoMcpTimeout.cs index 6f0376bf..2b1c9cc9 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigInfoMcpTimeout.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigInfoMcpTimeout.cs @@ -9,21 +9,21 @@ namespace OpenCode.Sdk.Models; public sealed record ConfigInfoMcpTimeout { /// - /// Gets the startup value. + /// Maximum time in milliseconds to establish and initialize the MCP server. /// [JsonPropertyName("startup")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public long? Startup { get; init; } /// - /// Gets the catalog value. + /// Maximum time in milliseconds to wait for MCP discovery requests such as tools/list and prompts/list. /// [JsonPropertyName("catalog")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public long? Catalog { get; init; } /// - /// Gets the execution value. + /// Maximum time in milliseconds to wait for MCP tool and prompt execution. /// [JsonPropertyName("execution")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettings.cs b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettings.cs index d80ec795..e24d41d2 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettings.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettings.cs @@ -11,21 +11,21 @@ namespace OpenCode.Sdk.Models; public sealed record ConfigProviderSettings { /// - /// Gets the timeout value. + /// HTTP timeout in milliseconds, or false to disable it. /// [JsonPropertyName("timeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public ConfigProviderSettingsTimeout? Timeout { get; init; } /// - /// Gets the header timeout value. + /// Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms. /// [JsonPropertyName("headerTimeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public ConfigProviderSettingsHeaderTimeout? HeaderTimeout { get; init; } /// - /// Gets the chunk timeout value. + /// Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms. /// [JsonPropertyName("chunkTimeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsChunkTimeout.cs b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsChunkTimeout.cs index d0063ee1..9a4494e2 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsChunkTimeout.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsChunkTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a config provider settings chunk timeout structural union. +/// Represents the timeout setting's alternatives. Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms. /// [JsonConverter(typeof(ConfigProviderSettingsChunkTimeoutJsonConverter))] public sealed record ConfigProviderSettingsChunkTimeout diff --git a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsHeaderTimeout.cs b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsHeaderTimeout.cs index d9dc7b8a..47e2e80b 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsHeaderTimeout.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsHeaderTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a config provider settings header timeout structural union. +/// Represents the timeout setting's alternatives. Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms. /// [JsonConverter(typeof(ConfigProviderSettingsHeaderTimeoutJsonConverter))] public sealed record ConfigProviderSettingsHeaderTimeout diff --git a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsTimeout.cs b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsTimeout.cs index f911ecce..5eca4884 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsTimeout.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigProviderSettingsTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a config provider settings timeout structural union. +/// Represents the timeout setting's alternatives. HTTP timeout in milliseconds, or false to disable it. /// [JsonConverter(typeof(ConfigProviderSettingsTimeoutJsonConverter))] public sealed record ConfigProviderSettingsTimeout diff --git a/src/OpenCode.Sdk/Config/Models/ConfigWarming.cs b/src/OpenCode.Sdk/Config/Models/ConfigWarming.cs index a706885e..a59f4f00 100644 --- a/src/OpenCode.Sdk/Config/Models/ConfigWarming.cs +++ b/src/OpenCode.Sdk/Config/Models/ConfigWarming.cs @@ -16,14 +16,14 @@ public sealed record ConfigWarming public string? Prompt { get; init; } /// - /// Gets the interval value. + /// Idle time between keep-alive requests, as a duration string; default “4 minutes”. /// [JsonPropertyName("interval")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string? Interval { get; init; } /// - /// Gets the duration value. + /// Time after the last active request to keep a session warm, as a duration string; default “30 minutes”. /// [JsonPropertyName("duration")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Credentials/CredentialsClient.cs b/src/OpenCode.Sdk/Credentials/CredentialsClient.cs index b5295ffa..a7968070 100644 --- a/src/OpenCode.Sdk/Credentials/CredentialsClient.cs +++ b/src/OpenCode.Sdk/Credentials/CredentialsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'CredentialsClient' collection client. +/// Lists, stores, labels, activates and removes integration credentials. /// public class CredentialsClient { diff --git a/src/OpenCode.Sdk/Debug/DebugClient.cs b/src/OpenCode.Sdk/Debug/DebugClient.cs index 2986f64f..b8765289 100644 --- a/src/OpenCode.Sdk/Debug/DebugClient.cs +++ b/src/OpenCode.Sdk/Debug/DebugClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'DebugClient' collection client. +/// Lists loaded locations and evicts their cached services. /// public class DebugClient { diff --git a/src/OpenCode.Sdk/Events/EventsClient.cs b/src/OpenCode.Sdk/Events/EventsClient.cs index d0faeace..2d1786f5 100644 --- a/src/OpenCode.Sdk/Events/EventsClient.cs +++ b/src/OpenCode.Sdk/Events/EventsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'EventsClient' collection client. +/// Experimental event stream routes. /// public class EventsClient { diff --git a/src/OpenCode.Sdk/Events/Models/EventLogSynced.cs b/src/OpenCode.Sdk/Events/Models/EventLogSynced.cs index 9b92ddaf..5306fc4b 100644 --- a/src/OpenCode.Sdk/Events/Models/EventLogSynced.cs +++ b/src/OpenCode.Sdk/Events/Models/EventLogSynced.cs @@ -22,7 +22,7 @@ public sealed record EventLogSynced : ISessionLogItem public required string AggregateId { get; init; } /// - /// Gets the seq value. + /// Captured watermark of this aggregate's durable log; absent when that watermark is empty. /// [JsonPropertyName("seq")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Events/Models/TuiToastShowData.cs b/src/OpenCode.Sdk/Events/Models/TuiToastShowData.cs index f63fed16..288d492e 100644 --- a/src/OpenCode.Sdk/Events/Models/TuiToastShowData.cs +++ b/src/OpenCode.Sdk/Events/Models/TuiToastShowData.cs @@ -28,7 +28,7 @@ public sealed record TuiToastShowData public required TuiToastShowDataVariant Variant { get; init; } /// - /// Gets the duration value. + /// Duration in milliseconds. /// [JsonPropertyName("duration")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Experimental/ExperimentalClient.cs b/src/OpenCode.Sdk/Experimental/ExperimentalClient.cs index ee70ac15..4b1869e6 100644 --- a/src/OpenCode.Sdk/Experimental/ExperimentalClient.cs +++ b/src/OpenCode.Sdk/Experimental/ExperimentalClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'ExperimentalClient' collection client. +/// Provides experimental generation, session, integration, MCP, filesystem, configuration and migration operations. /// [System.Diagnostics.CodeAnalysis.Experimental("OPENCODE001", UrlFormat = "https://github.com/opencode-dotnet/opencode-sdk-dotnet/blob/master/docs/guide/experimental.md#opencode001")] public class ExperimentalClient diff --git a/src/OpenCode.Sdk/Experimental/ExperimentalSessionStatsRequest.cs b/src/OpenCode.Sdk/Experimental/ExperimentalSessionStatsRequest.cs index a45f4bdb..bdbaff79 100644 --- a/src/OpenCode.Sdk/Experimental/ExperimentalSessionStatsRequest.cs +++ b/src/OpenCode.Sdk/Experimental/ExperimentalSessionStatsRequest.cs @@ -10,11 +10,11 @@ namespace OpenCode.Sdk; public sealed record ExperimentalSessionStatsRequest { /// - /// The start of the range, inclusive, in milliseconds since the Unix epoch. Unset, the range starts at the earliest message. + /// Gets the 'from' query value; the server default applies when unset. /// public long? From { get; init; } /// - /// The end of the range, exclusive, in milliseconds since the Unix epoch. Unset, the range ends now. + /// Gets the 'to' query value; the server default applies when unset. /// public long? To { get; init; } /// diff --git a/src/OpenCode.Sdk/FileSystem/FileSystemClient.cs b/src/OpenCode.Sdk/FileSystem/FileSystemClient.cs index 42d3ca8f..06320dd1 100644 --- a/src/OpenCode.Sdk/FileSystem/FileSystemClient.cs +++ b/src/OpenCode.Sdk/FileSystem/FileSystemClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'FileSystemClient' collection client. +/// Reads file content and lists or finds entries at the requested location. /// public class FileSystemClient { diff --git a/src/OpenCode.Sdk/Forms/FormsClient.cs b/src/OpenCode.Sdk/Forms/FormsClient.cs index b7591065..306cd9d9 100644 --- a/src/OpenCode.Sdk/Forms/FormsClient.cs +++ b/src/OpenCode.Sdk/Forms/FormsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'FormsClient' collection client. +/// Location form routes. /// public class FormsClient { diff --git a/src/OpenCode.Sdk/Integrations/IntegrationsClient.cs b/src/OpenCode.Sdk/Integrations/IntegrationsClient.cs index 1f32235f..e74027b0 100644 --- a/src/OpenCode.Sdk/Integrations/IntegrationsClient.cs +++ b/src/OpenCode.Sdk/Integrations/IntegrationsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'IntegrationsClient' collection client. +/// Discovers integrations and runs key, external, OAuth or command authentication flows. /// public class IntegrationsClient { diff --git a/src/OpenCode.Sdk/LanguageModels/LanguageModelsClient.cs b/src/OpenCode.Sdk/LanguageModels/LanguageModelsClient.cs index a2353e28..9c844baf 100644 --- a/src/OpenCode.Sdk/LanguageModels/LanguageModelsClient.cs +++ b/src/OpenCode.Sdk/LanguageModels/LanguageModelsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'LanguageModelsClient' collection client. +/// Experimental model routes. /// public class LanguageModelsClient { diff --git a/src/OpenCode.Sdk/LanguageModels/Models/ModelInfoTime.cs b/src/OpenCode.Sdk/LanguageModels/Models/ModelInfoTime.cs index 9e64d7dc..a4d9802c 100644 --- a/src/OpenCode.Sdk/LanguageModels/Models/ModelInfoTime.cs +++ b/src/OpenCode.Sdk/LanguageModels/Models/ModelInfoTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record ModelInfoTime { /// - /// Gets the released value. + /// Release date as a Unix timestamp in milliseconds, or 0 when unknown. /// [JsonPropertyName("released")] public required double Released { get; init; } diff --git a/src/OpenCode.Sdk/McpServers/McpServersClient.cs b/src/OpenCode.Sdk/McpServers/McpServersClient.cs index d44ee4e4..4a0ab54d 100644 --- a/src/OpenCode.Sdk/McpServers/McpServersClient.cs +++ b/src/OpenCode.Sdk/McpServers/McpServersClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'McpServersClient' collection client. +/// Lists MCP servers and discovers their resources and resource templates. /// public class McpServersClient { diff --git a/src/OpenCode.Sdk/OpenCodeClient.cs b/src/OpenCode.Sdk/OpenCodeClient.cs index 4ca552b8..ab39f9cb 100644 --- a/src/OpenCode.Sdk/OpenCodeClient.cs +++ b/src/OpenCode.Sdk/OpenCodeClient.cs @@ -138,115 +138,115 @@ protected virtual void Dispose(bool disposing) } /// - /// Gets the 'Agents' collection client. + /// Lists registered agents and retrieves an agent by identifier. /// public virtual AgentsClient Agents => _agents ?? throw MockSeam.CreateError("OpenCodeClient", "Agents"); /// - /// Gets the 'Commands' collection client. + /// Experimental command routes. /// public virtual CommandsClient Commands => _commands ?? throw MockSeam.CreateError("OpenCodeClient", "Commands"); /// - /// Gets the 'Config' collection client. + /// Reads the location's configuration documents and lists shells available for terminal and agent execution. /// public virtual ConfigClient Config => _config ?? throw MockSeam.CreateError("OpenCodeClient", "Config"); /// - /// Gets the 'Credentials' collection client. + /// Lists, stores, labels, activates and removes integration credentials. /// public virtual CredentialsClient Credentials => _credentials ?? throw MockSeam.CreateError("OpenCodeClient", "Credentials"); /// - /// Gets the 'Debug' collection client. + /// Lists loaded locations and evicts their cached services. /// public virtual DebugClient Debug => _debug ?? throw MockSeam.CreateError("OpenCodeClient", "Debug"); /// - /// Gets the 'Events' collection client. + /// Experimental event stream routes. /// public virtual EventsClient Events => _events ?? throw MockSeam.CreateError("OpenCodeClient", "Events"); /// - /// Gets the 'Experimental' collection client. + /// Provides experimental generation, session, integration, MCP, filesystem, configuration and migration operations. /// [System.Diagnostics.CodeAnalysis.Experimental("OPENCODE001", UrlFormat = "https://github.com/opencode-dotnet/opencode-sdk-dotnet/blob/master/docs/guide/experimental.md#opencode001")] public virtual ExperimentalClient Experimental => _experimental ?? throw MockSeam.CreateError("OpenCodeClient", "Experimental"); /// - /// Gets the 'FileSystem' collection client. + /// Reads file content and lists or finds entries at the requested location. /// public virtual FileSystemClient FileSystem => _fileSystem ?? throw MockSeam.CreateError("OpenCodeClient", "FileSystem"); /// - /// Gets the 'Forms' collection client. + /// Location form routes. /// public virtual FormsClient Forms => _forms ?? throw MockSeam.CreateError("OpenCodeClient", "Forms"); /// - /// Gets the 'Integrations' collection client. + /// Discovers integrations and runs key, external, OAuth or command authentication flows. /// public virtual IntegrationsClient Integrations => _integrations ?? throw MockSeam.CreateError("OpenCodeClient", "Integrations"); /// - /// Gets the 'LanguageModels' collection client. + /// Experimental model routes. /// public virtual LanguageModelsClient LanguageModels => _languageModels ?? throw MockSeam.CreateError("OpenCodeClient", "LanguageModels"); /// - /// Gets the 'McpServers' collection client. + /// Lists MCP servers and discovers their resources and resource templates. /// public virtual McpServersClient McpServers => _mcpServers ?? throw MockSeam.CreateError("OpenCodeClient", "McpServers"); /// - /// Gets the 'Permissions' collection client. + /// Lists location permission requests and saved permissions, and removes saved permissions. /// public virtual PermissionsClient Permissions => _permissions ?? throw MockSeam.CreateError("OpenCodeClient", "Permissions"); /// - /// Gets the 'PersistentPtys' collection client. + /// Prototype persistent PTY routes. /// [System.Diagnostics.CodeAnalysis.Experimental("OPENCODE002", UrlFormat = "https://github.com/opencode-dotnet/opencode-sdk-dotnet/blob/master/docs/guide/experimental.md#opencode002")] public virtual PersistentPtysClient PersistentPtys => _persistentPtys ?? throw MockSeam.CreateError("OpenCodeClient", "PersistentPtys"); /// - /// Gets the 'Plugins' collection client. + /// Experimental plugin routes. /// public virtual PluginsClient Plugins => _plugins ?? throw MockSeam.CreateError("OpenCodeClient", "Plugins"); /// - /// Gets the 'Projects' collection client. + /// Project routes. /// public virtual ProjectsClient Projects => _projects ?? throw MockSeam.CreateError("OpenCodeClient", "Projects"); /// - /// Gets the 'Providers' collection client. + /// Experimental provider routes. /// public virtual ProvidersClient Providers => _providers ?? throw MockSeam.CreateError("OpenCodeClient", "Providers"); /// - /// Gets the 'Ptys' collection client. + /// Experimental location-scoped PTY routes. /// public virtual PtysClient Ptys => _ptys ?? throw MockSeam.CreateError("OpenCodeClient", "Ptys"); /// - /// Gets the 'References' collection client. + /// Location-scoped project references. /// public virtual ReferencesClient References => _references ?? throw MockSeam.CreateError("OpenCodeClient", "References"); /// - /// Gets the 'Rpc' collection client. + /// Plugin RPC routes. /// public virtual RpcClient Rpc => _rpc ?? throw MockSeam.CreateError("OpenCodeClient", "Rpc"); /// - /// Gets the 'Server' collection client. + /// Reads server identity and readiness and creates or consumes pairing links. /// public virtual ServerClient Server => _server ?? throw MockSeam.CreateError("OpenCodeClient", "Server"); /// - /// Gets the 'Sessions' collection client. + /// Creates and lists sessions and opens session handles for prompts, messages, forms and execution control. /// public virtual SessionsClient Sessions => _sessions ?? throw MockSeam.CreateError("OpenCodeClient", "Sessions"); /// - /// Gets the 'Shells' collection client. + /// Location-scoped shell command routes. /// public virtual ShellsClient Shells => _shells ?? throw MockSeam.CreateError("OpenCodeClient", "Shells"); /// - /// Gets the 'Skills' collection client. + /// Experimental skill routes. /// public virtual SkillsClient Skills => _skills ?? throw MockSeam.CreateError("OpenCodeClient", "Skills"); /// - /// Gets the 'Vcs' collection client. + /// Location-scoped version control routes. /// public virtual VcsClient Vcs => _vcs ?? throw MockSeam.CreateError("OpenCodeClient", "Vcs"); /// - /// Gets the 'Websearch' collection client. + /// Location-scoped web search routes. /// public virtual WebsearchClient Websearch => _websearch ?? throw MockSeam.CreateError("OpenCodeClient", "Websearch"); /// - /// Gets the 'Worktrees' collection client. + /// Project-based worktree management routes. /// public virtual WorktreesClient Worktrees => _worktrees ?? throw MockSeam.CreateError("OpenCodeClient", "Worktrees"); private Pipeline Pipeline => _pipeline ?? throw MockSeam.CreateError("OpenCodeClient", "Pipeline"); diff --git a/src/OpenCode.Sdk/Permissions/Models/PermissionSavedInfoTime.cs b/src/OpenCode.Sdk/Permissions/Models/PermissionSavedInfoTime.cs index b92a483e..4b0a3371 100644 --- a/src/OpenCode.Sdk/Permissions/Models/PermissionSavedInfoTime.cs +++ b/src/OpenCode.Sdk/Permissions/Models/PermissionSavedInfoTime.cs @@ -9,13 +9,13 @@ namespace OpenCode.Sdk.Models; public sealed record PermissionSavedInfoTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the updated value. + /// Update time in milliseconds since the Unix epoch. /// [JsonPropertyName("updated")] public required double Updated { get; init; } diff --git a/src/OpenCode.Sdk/Permissions/PermissionsClient.cs b/src/OpenCode.Sdk/Permissions/PermissionsClient.cs index 42cc29af..6c2f5148 100644 --- a/src/OpenCode.Sdk/Permissions/PermissionsClient.cs +++ b/src/OpenCode.Sdk/Permissions/PermissionsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'PermissionsClient' collection client. +/// Lists location permission requests and saved permissions, and removes saved permissions. /// public class PermissionsClient { diff --git a/src/OpenCode.Sdk/Plugins/PluginsClient.cs b/src/OpenCode.Sdk/Plugins/PluginsClient.cs index 276f3f31..9542784c 100644 --- a/src/OpenCode.Sdk/Plugins/PluginsClient.cs +++ b/src/OpenCode.Sdk/Plugins/PluginsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'PluginsClient' collection client. +/// Experimental plugin routes. /// public class PluginsClient { diff --git a/src/OpenCode.Sdk/Projects/ProjectsClient.cs b/src/OpenCode.Sdk/Projects/ProjectsClient.cs index 58a7849d..0a3289ca 100644 --- a/src/OpenCode.Sdk/Projects/ProjectsClient.cs +++ b/src/OpenCode.Sdk/Projects/ProjectsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'ProjectsClient' collection client. +/// Project routes. /// public class ProjectsClient { diff --git a/src/OpenCode.Sdk/Providers/Models/ProviderSettings.cs b/src/OpenCode.Sdk/Providers/Models/ProviderSettings.cs index 16d8a9f9..1a61dcab 100644 --- a/src/OpenCode.Sdk/Providers/Models/ProviderSettings.cs +++ b/src/OpenCode.Sdk/Providers/Models/ProviderSettings.cs @@ -11,21 +11,21 @@ namespace OpenCode.Sdk.Models; public sealed record ProviderSettings { /// - /// Gets the timeout value. + /// HTTP timeout in milliseconds, or false to disable it. /// [JsonPropertyName("timeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public ProviderSettingsTimeout? Timeout { get; init; } /// - /// Gets the header timeout value. + /// Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms. /// [JsonPropertyName("headerTimeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public ProviderSettingsHeaderTimeout? HeaderTimeout { get; init; } /// - /// Gets the chunk timeout value. + /// Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms. /// [JsonPropertyName("chunkTimeout")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsChunkTimeout.cs b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsChunkTimeout.cs index 70952aa8..8602058f 100644 --- a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsChunkTimeout.cs +++ b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsChunkTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a provider settings chunk timeout structural union. +/// Represents the timeout setting's alternatives. Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms. /// [JsonConverter(typeof(ProviderSettingsChunkTimeoutJsonConverter))] public sealed record ProviderSettingsChunkTimeout diff --git a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsHeaderTimeout.cs b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsHeaderTimeout.cs index 992aa3af..907c9c4d 100644 --- a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsHeaderTimeout.cs +++ b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsHeaderTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a provider settings header timeout structural union. +/// Represents the timeout setting's alternatives. Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms. /// [JsonConverter(typeof(ProviderSettingsHeaderTimeoutJsonConverter))] public sealed record ProviderSettingsHeaderTimeout diff --git a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsTimeout.cs b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsTimeout.cs index fb709f7d..a2f4b29e 100644 --- a/src/OpenCode.Sdk/Providers/Models/ProviderSettingsTimeout.cs +++ b/src/OpenCode.Sdk/Providers/Models/ProviderSettingsTimeout.cs @@ -6,7 +6,7 @@ namespace OpenCode.Sdk.Models; /// -/// Represents a provider settings timeout structural union. +/// Represents the timeout setting's alternatives. HTTP timeout in milliseconds, or false to disable it. /// [JsonConverter(typeof(ProviderSettingsTimeoutJsonConverter))] public sealed record ProviderSettingsTimeout diff --git a/src/OpenCode.Sdk/Providers/ProvidersClient.cs b/src/OpenCode.Sdk/Providers/ProvidersClient.cs index f2a59308..d7ef47b2 100644 --- a/src/OpenCode.Sdk/Providers/ProvidersClient.cs +++ b/src/OpenCode.Sdk/Providers/ProvidersClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'ProvidersClient' collection client. +/// Experimental provider routes. /// public class ProvidersClient { diff --git a/src/OpenCode.Sdk/Ptys/PtyCreateRequest.cs b/src/OpenCode.Sdk/Ptys/PtyCreateRequest.cs index 5ddb4e09..c47b2336 100644 --- a/src/OpenCode.Sdk/Ptys/PtyCreateRequest.cs +++ b/src/OpenCode.Sdk/Ptys/PtyCreateRequest.cs @@ -10,21 +10,15 @@ namespace OpenCode.Sdk.Models; public sealed record PtyCreateRequest { /// - /// The program to run, an executable rather than a command line. When it is absent the server picks a shell: the configured shell, then $SHELL, then a per-platform fallback. + /// Gets the command value. /// - /// - /// The fallback is, on Windows, the first of pwsh, powershell and Git Bash that is found, otherwise %COMSPEC%, or cmd.exe when COMSPEC is unset; /bin/zsh on macOS; and bash on PATH, or else /bin/sh, elsewhere. A configured shell that is not executable skips $SHELL and goes straight to the fallback. PowerShell starts with no added arguments, so its profile loads; pass -NoProfile in Args for a clean one. - /// [JsonPropertyName("command")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string? Command { get; init; } /// - /// Arguments passed as they are to the program, with no shell parsing. + /// Gets the args value. /// - /// - /// When the program is bash, dash, fish, ksh, sh or zsh, the server appends -l after these arguments, so bash -c "cmd" receives -l as $0; the returned info shows it. - /// [JsonPropertyName("args")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public IReadOnlyList? Args { get; init; } diff --git a/src/OpenCode.Sdk/References/ReferencesClient.cs b/src/OpenCode.Sdk/References/ReferencesClient.cs index fdf5d6ec..cf237ef9 100644 --- a/src/OpenCode.Sdk/References/ReferencesClient.cs +++ b/src/OpenCode.Sdk/References/ReferencesClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'ReferencesClient' collection client. +/// Location-scoped project references. /// public class ReferencesClient { diff --git a/src/OpenCode.Sdk/Rpc/RpcClient.cs b/src/OpenCode.Sdk/Rpc/RpcClient.cs index 4278b161..e8b0ddb5 100644 --- a/src/OpenCode.Sdk/Rpc/RpcClient.cs +++ b/src/OpenCode.Sdk/Rpc/RpcClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'RpcClient' collection client. +/// Plugin RPC routes. /// public class RpcClient { diff --git a/src/OpenCode.Sdk/Server/ServerClient.cs b/src/OpenCode.Sdk/Server/ServerClient.cs index 85c3504b..0c27eeb8 100644 --- a/src/OpenCode.Sdk/Server/ServerClient.cs +++ b/src/OpenCode.Sdk/Server/ServerClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'ServerClient' collection client. +/// Reads server identity and readiness and creates or consumes pairing links. /// public class ServerClient { diff --git a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionFailed.cs b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionFailed.cs index 5c2a444f..de67dd2b 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionFailed.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionFailed.cs @@ -5,11 +5,8 @@ namespace OpenCode.Sdk.Models; /// -/// The session stopped on an error and went idle; its Data.Error says why. +/// The 'session.execution.failed' event. /// -/// -/// It is also published when a turn interrupted by repeated restarts can no longer be resumed. -/// public sealed record SessionExecutionFailed : ISessionEventDurable, IEvent, ISessionScopedEvent { /// diff --git a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionInterrupted.cs b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionInterrupted.cs index 44e17d35..0eb7d4e7 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionInterrupted.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionInterrupted.cs @@ -5,11 +5,8 @@ namespace OpenCode.Sdk.Models; /// -/// The session's work stopped before it finished; its Data.Reason says why. +/// The 'session.execution.interrupted' event. /// -/// -/// With the shutdown reason the turn is not over: the server keeps it marked in progress, and a server that resumes work after it restarts picks it up again with a new SessionExecutionStarted. A turn that cannot be resumed, or has been resumed too often, ends with SessionExecutionFailed. -/// public sealed record SessionExecutionInterrupted : ISessionEventDurable, IEvent, ISessionScopedEvent { /// diff --git a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionStarted.cs b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionStarted.cs index 37508bcf..a279a08f 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionStarted.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionStarted.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk.Models; /// -/// The server began working on the session after it was woken while idle. When that work settles, exactly one of SessionExecutionSucceeded, SessionExecutionFailed or SessionExecutionInterrupted follows, however many prompts arrive meanwhile; a server that crashes mid-work publishes none. +/// The 'session.execution.started' event. /// public sealed record SessionExecutionStarted : ISessionEventDurable, IEvent, ISessionScopedEvent { diff --git a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionSucceeded.cs b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionSucceeded.cs index a5d792d9..c8b4ed70 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionSucceeded.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Execution/SessionExecutionSucceeded.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk.Models; /// -/// The execution finished the work it took on and the session went idle. Prompts it did not take, such as queued ones, can still be pending. +/// The 'session.execution.succeeded' event. /// public sealed record SessionExecutionSucceeded : ISessionEventDurable, IEvent, ISessionScopedEvent { diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAgentSelectedTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAgentSelectedTime.cs index 1ecc6394..553e14a9 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAgentSelectedTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAgentSelectedTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageAgentSelectedTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistant.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistant.cs index 4cff4ed8..056c3e89 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistant.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistant.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk.Models; /// -/// One model step's response within a turn. A single prompt can produce several, for example one per round of tool calls; a step that failed keeps its message, with Error set and any partial content. +/// Represents a session message assistant value. /// public sealed record SessionMessageAssistant : ISessionMessageInfo { @@ -47,7 +47,7 @@ public sealed record SessionMessageAssistant : ISessionMessageInfo public required ModelRef Model { get; init; } /// - /// The step's output parts in the order they streamed: text, reasoning and tool calls. + /// Gets the content value. /// [JsonPropertyName("content")] public required IReadOnlyList Content { get; init; } @@ -60,17 +60,14 @@ public sealed record SessionMessageAssistant : ISessionMessageInfo public SessionMessageAssistantSnapshot? Snapshot { get; init; } /// - /// Why the step ended: stop, length, tool-calls, content-filter, error or unknown; null while the step is still running. + /// Gets the finish value. /// - /// - /// A step that failed reports error, or content-filter when the provider blocked the response. - /// [JsonPropertyName("finish")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public SessionMessageAssistantFinish? Finish { get; init; } /// - /// The provider's own finish-reason string, kept verbatim for diagnostics; it may be null. Use Finish for logic. + /// Gets the raw finish value. /// [JsonPropertyName("rawFinish")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] @@ -84,35 +81,29 @@ public sealed record SessionMessageAssistant : ISessionMessageInfo public IReadOnlyDictionary? ProviderState { get; init; } /// - /// The cost in US dollars of this step alone, computed by the server from the model's configured prices; null until the step finishes, and it may stay null when the step fails. + /// Gets the cost value. /// [JsonPropertyName("cost")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public double? Cost { get; init; } /// - /// The token usage of this step alone; null until the step finishes, and it may stay null when the step fails. + /// Gets the tokens value. /// [JsonPropertyName("tokens")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public TokenUsageInfo? Tokens { get; init; } /// - /// Set when this step failed, for example a provider error, a content filter or an interruption; the message and its partial content stay in the session. + /// Gets the error value. /// - /// - /// It is cleared when the step starts again on this same message. When a failure after partial output continues the turn, the continuation is a new message and this one keeps its error. - /// [JsonPropertyName("error")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public SessionStructuredError? Error { get; init; } /// - /// Set while a retry of this step is scheduled after a retryable provider error: the attempt number (the first retry is 2), when it runs, and the error that caused it. + /// Gets the retry value. /// - /// - /// It is cleared when the retry starts or the session goes idle. - /// [JsonPropertyName("retry")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public SessionMessageAssistantRetry? Retry { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantReasoningTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantReasoningTime.cs index c03d7bbf..49b417c4 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantReasoningTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantReasoningTime.cs @@ -9,13 +9,13 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageAssistantReasoningTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the completed value. + /// Completion time in milliseconds since the Unix epoch. /// [JsonPropertyName("completed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantRetry.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantRetry.cs index 0baa9215..2fdd973e 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantRetry.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantRetry.cs @@ -15,7 +15,7 @@ public sealed record SessionMessageAssistantRetry public required long Attempt { get; init; } /// - /// Gets the at value. + /// Scheduled retry time in milliseconds since the Unix epoch. /// [JsonPropertyName("at")] public required double At { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantTime.cs index 5446bf8d..4170e8bc 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantTime.cs @@ -9,20 +9,20 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageAssistantTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the streamed value. + /// Time the provider response body ended, before tool settlement, in milliseconds since the Unix epoch. /// [JsonPropertyName("streamed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public double? Streamed { get; init; } /// - /// Gets the completed value. + /// Completion time in milliseconds since the Unix epoch. /// [JsonPropertyName("completed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantToolTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantToolTime.cs index 966de623..ef6911ed 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantToolTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageAssistantToolTime.cs @@ -9,20 +9,20 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageAssistantToolTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the ran value. + /// Run time in milliseconds since the Unix epoch. /// [JsonPropertyName("ran")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public double? Ran { get; init; } /// - /// Gets the completed value. + /// Completion time in milliseconds since the Unix epoch. /// [JsonPropertyName("completed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageIdleTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageIdleTime.cs index 6b8d5d79..655e1f2e 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageIdleTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageIdleTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageIdleTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageLocationSwitchedTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageLocationSwitchedTime.cs index 9d72d720..7f05bc65 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageLocationSwitchedTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageLocationSwitchedTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageLocationSwitchedTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageModelSelectedTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageModelSelectedTime.cs index ae0f6536..63d58e0b 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageModelSelectedTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageModelSelectedTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageModelSelectedTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageShellTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageShellTime.cs index ffd023fd..0ef87be7 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageShellTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageShellTime.cs @@ -9,13 +9,13 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageShellTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the completed value. + /// Completion time in milliseconds since the Unix epoch. /// [JsonPropertyName("completed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSkillTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSkillTime.cs index 24d56c38..56dd6415 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSkillTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSkillTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageSkillTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSyntheticTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSyntheticTime.cs index 76740e03..6ffe9cf5 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSyntheticTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSyntheticTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageSyntheticTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSystemTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSystemTime.cs index c74c5cf0..535c7696 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSystemTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageSystemTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageSystemTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageUserTime.cs b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageUserTime.cs index 8c84314e..649b1415 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageUserTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Messages/SessionMessageUserTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record SessionMessageUserTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/SessionInfoTime.cs b/src/OpenCode.Sdk/Sessions/Models/SessionInfoTime.cs index d0a9247e..2df28bad 100644 --- a/src/OpenCode.Sdk/Sessions/Models/SessionInfoTime.cs +++ b/src/OpenCode.Sdk/Sessions/Models/SessionInfoTime.cs @@ -9,33 +9,33 @@ namespace OpenCode.Sdk.Models; public sealed record SessionInfoTime { /// - /// Gets the created value. + /// Creation time in milliseconds since the Unix epoch. /// [JsonPropertyName("created")] public required double Created { get; init; } /// - /// Gets the updated value. + /// Update time in milliseconds since the Unix epoch. /// [JsonPropertyName("updated")] public required double Updated { get; init; } /// - /// Gets the idle value. + /// Idle time in milliseconds since the Unix epoch. /// [JsonPropertyName("idle")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public double? Idle { get; init; } /// - /// Gets the viewed value. + /// Viewed time in milliseconds since the Unix epoch. /// [JsonPropertyName("viewed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public double? Viewed { get; init; } /// - /// Gets the archived value. + /// Archive time in milliseconds since the Unix epoch. /// [JsonPropertyName("archived")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextDeltaData.cs b/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextDeltaData.cs index dff2ff16..8ff585aa 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextDeltaData.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextDeltaData.cs @@ -21,16 +21,13 @@ public sealed record SessionTextDeltaData public required string AssistantMessageId { get; init; } /// - /// The zero-based index of this text part among the text parts of its assistant message; the started, delta and ended events of one part share it. + /// Gets the ordinal value. /// - /// - /// Reasoning parts are numbered separately. - /// [JsonPropertyName("ordinal")] public required long Ordinal { get; init; } /// - /// The new text to append; it may batch several provider chunks. + /// Gets the delta value. /// [JsonPropertyName("delta")] public required string Delta { get; init; } diff --git a/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextEndedData.cs b/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextEndedData.cs index 03e32fab..9c99d31f 100644 --- a/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextEndedData.cs +++ b/src/OpenCode.Sdk/Sessions/Models/Turn/SessionTextEndedData.cs @@ -28,13 +28,13 @@ public sealed record SessionTextEndedData public required long Ordinal { get; init; } /// - /// The complete text of the part; it replaces whatever was built up from deltas. + /// Gets the text value. /// [JsonPropertyName("text")] public required string Text { get; init; } /// - /// Opaque provider metadata for the part, kept so it can be sent back to the provider; do not interpret it. + /// Gets the state value. /// [JsonPropertyName("state")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Sessions/SessionCreateRequest.cs b/src/OpenCode.Sdk/Sessions/SessionCreateRequest.cs index 9b3a9c4a..b9499c82 100644 --- a/src/OpenCode.Sdk/Sessions/SessionCreateRequest.cs +++ b/src/OpenCode.Sdk/Sessions/SessionCreateRequest.cs @@ -6,12 +6,12 @@ namespace OpenCode.Sdk.Models; /// -/// A new session, or, when Id names an existing one, that session returned unchanged. +/// The body of 'session.create' (POST /api/session). /// public sealed record SessionCreateRequest { /// - /// An optional session id of your own; when a session with it exists, that session is returned and the other members are ignored. + /// Gets the id value. /// [JsonPropertyName("id")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] @@ -19,11 +19,8 @@ public sealed record SessionCreateRequest public Optional Id { get; init; } /// - /// Makes this a child session, such as a subagent's, of an existing parent. The child always works in the parent's location and inherits its metadata and permissions unless you set them. + /// Gets the parent id value. /// - /// - /// Agent and model are not inherited. - /// [JsonPropertyName("parentID")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonConverter(typeof(OptionalOfStringJsonConverter))] @@ -38,7 +35,7 @@ public sealed record SessionCreateRequest public Optional Title { get; init; } /// - /// The agent to use. When it is absent, the server chooses its default agent each time the session runs a step. + /// Gets the agent value. /// [JsonPropertyName("agent")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] @@ -46,7 +43,7 @@ public sealed record SessionCreateRequest public Optional Agent { get; init; } /// - /// The model to use. When it is absent, the server chooses its default model each time the session runs a step; an unavailable model is reported only when the session runs. + /// Gets the model value. /// [JsonPropertyName("model")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] @@ -54,7 +51,7 @@ public sealed record SessionCreateRequest public Optional Model { get; init; } /// - /// The directory the session works in; the server's working directory when absent. It is ignored when ParentId is set. + /// Gets the location value. /// [JsonPropertyName("location")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] @@ -70,7 +67,7 @@ public sealed record SessionCreateRequest public Optional?> Metadata { get; init; } /// - /// Session permission rules, checked after the agent's own; the last rule that matches wins, so they override the agent. Anything no rule matches asks. + /// Gets the permissions value. /// [JsonPropertyName("permissions")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] diff --git a/src/OpenCode.Sdk/Sessions/SessionPromptRequest.cs b/src/OpenCode.Sdk/Sessions/SessionPromptRequest.cs index 4a3febde..c28cda14 100644 --- a/src/OpenCode.Sdk/Sessions/SessionPromptRequest.cs +++ b/src/OpenCode.Sdk/Sessions/SessionPromptRequest.cs @@ -6,16 +6,13 @@ namespace OpenCode.Sdk.Models; /// -/// A prompt for the session's inbox. The call returns as soon as the prompt is stored, before the model runs; follow the turn on the event bus or with the experimental wait. +/// The body of 'session.prompt' (POST /api/session/{sessionID}/prompt). /// public sealed record SessionPromptRequest { /// - /// An optional message id of your own, starting with msg_, which makes the call idempotent: resending it returns the stored item and ignores the new content. + /// Gets the id value. /// - /// - /// An id that belongs to another session or another kind of record is a conflict (409). - /// [JsonPropertyName("id")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] [JsonConverter(typeof(OptionalOfStringJsonConverter))] @@ -28,7 +25,7 @@ public sealed record SessionPromptRequest public required string Text { get; init; } /// - /// Attachments as data: URIs, or file: URIs on the server's own file system, read when the prompt is submitted; at most 20 MiB each. + /// Gets the files value. /// [JsonPropertyName("files")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] @@ -42,7 +39,7 @@ public sealed record SessionPromptRequest public IReadOnlyList? Agents { get; init; } /// - /// Skills to attach by id; the server puts each skill's text before the prompt, and an unknown id is refused (400). + /// Gets the skills value. /// [JsonPropertyName("skills")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] @@ -56,7 +53,7 @@ public sealed record SessionPromptRequest public IReadOnlyDictionary? Metadata { get; init; } /// - /// Steer, the default, puts the prompt into the running turn at its next step; Queue waits for the current turn to end and starts a new turn with it. + /// Gets the delivery value. /// [JsonPropertyName("delivery")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] @@ -64,7 +61,7 @@ public sealed record SessionPromptRequest public Optional Delivery { get; init; } /// - /// False stores the prompt without waking the session for it: an idle session leaves it pending until something else wakes it, while a session already running can still take it at its next boundary. The default is true. + /// Gets the resume value. /// [JsonPropertyName("resume")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] diff --git a/src/OpenCode.Sdk/Sessions/SessionsClient.cs b/src/OpenCode.Sdk/Sessions/SessionsClient.cs index ba2c9f4f..d41f4af9 100644 --- a/src/OpenCode.Sdk/Sessions/SessionsClient.cs +++ b/src/OpenCode.Sdk/Sessions/SessionsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'SessionsClient' collection client. +/// Creates and lists sessions and opens session handles for prompts, messages, forms and execution control. /// public class SessionsClient { diff --git a/src/OpenCode.Sdk/Shells/Models/ShellInfoTime.cs b/src/OpenCode.Sdk/Shells/Models/ShellInfoTime.cs index c17412cd..53d38b07 100644 --- a/src/OpenCode.Sdk/Shells/Models/ShellInfoTime.cs +++ b/src/OpenCode.Sdk/Shells/Models/ShellInfoTime.cs @@ -15,7 +15,7 @@ public sealed record ShellInfoTime public required double Started { get; init; } /// - /// Gets the completed value. + /// Completion time in milliseconds since the Unix epoch. /// [JsonPropertyName("completed")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Shells/ShellsClient.cs b/src/OpenCode.Sdk/Shells/ShellsClient.cs index f5256ee4..997e297f 100644 --- a/src/OpenCode.Sdk/Shells/ShellsClient.cs +++ b/src/OpenCode.Sdk/Shells/ShellsClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'ShellsClient' collection client. +/// Location-scoped shell command routes. /// public class ShellsClient { diff --git a/src/OpenCode.Sdk/Skills/SkillsClient.cs b/src/OpenCode.Sdk/Skills/SkillsClient.cs index c48380bd..6e25a082 100644 --- a/src/OpenCode.Sdk/Skills/SkillsClient.cs +++ b/src/OpenCode.Sdk/Skills/SkillsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'SkillsClient' collection client. +/// Experimental skill routes. /// public class SkillsClient { diff --git a/src/OpenCode.Sdk/Vcs/VcsClient.cs b/src/OpenCode.Sdk/Vcs/VcsClient.cs index 09dc01c2..85df3eb6 100644 --- a/src/OpenCode.Sdk/Vcs/VcsClient.cs +++ b/src/OpenCode.Sdk/Vcs/VcsClient.cs @@ -4,7 +4,7 @@ namespace OpenCode.Sdk; /// -/// The 'VcsClient' collection client. +/// Location-scoped version control routes. /// public class VcsClient { diff --git a/src/OpenCode.Sdk/Websearch/Models/WebSearchResultTime.cs b/src/OpenCode.Sdk/Websearch/Models/WebSearchResultTime.cs index adf61e60..efaa7445 100644 --- a/src/OpenCode.Sdk/Websearch/Models/WebSearchResultTime.cs +++ b/src/OpenCode.Sdk/Websearch/Models/WebSearchResultTime.cs @@ -9,7 +9,7 @@ namespace OpenCode.Sdk.Models; public sealed record WebSearchResultTime { /// - /// Gets the published value. + /// Publication time in milliseconds since the Unix epoch. /// [JsonPropertyName("published")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] diff --git a/src/OpenCode.Sdk/Websearch/WebsearchClient.cs b/src/OpenCode.Sdk/Websearch/WebsearchClient.cs index d994db58..31254367 100644 --- a/src/OpenCode.Sdk/Websearch/WebsearchClient.cs +++ b/src/OpenCode.Sdk/Websearch/WebsearchClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'WebsearchClient' collection client. +/// Location-scoped web search routes. /// public class WebsearchClient { diff --git a/src/OpenCode.Sdk/Worktrees/Models/WorktreeResolvedDurable.cs b/src/OpenCode.Sdk/Worktrees/Models/WorktreeResolvedDurable.cs index 1d88158f..4873b663 100644 --- a/src/OpenCode.Sdk/Worktrees/Models/WorktreeResolvedDurable.cs +++ b/src/OpenCode.Sdk/Worktrees/Models/WorktreeResolvedDurable.cs @@ -15,13 +15,13 @@ public sealed record WorktreeResolvedDurable public required string AggregateId { get; init; } /// - /// Gets the seq value. + /// Position in one aggregate's durable log. Use only values from durable envelopes or synced markers as after cursors. /// [JsonPropertyName("seq")] public required long Seq { get; init; } /// - /// Gets the version value. + /// Durable schema version of this event type, from the event definition that committed it. /// [JsonPropertyName("version")] public required double Version { get; init; } diff --git a/src/OpenCode.Sdk/Worktrees/WorktreesClient.cs b/src/OpenCode.Sdk/Worktrees/WorktreesClient.cs index 2e3da523..88f7c77c 100644 --- a/src/OpenCode.Sdk/Worktrees/WorktreesClient.cs +++ b/src/OpenCode.Sdk/Worktrees/WorktreesClient.cs @@ -5,7 +5,7 @@ namespace OpenCode.Sdk; /// -/// The 'WorktreesClient' collection client. +/// Project-based worktree management routes. /// public class WorktreesClient { diff --git a/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/DescriptionCurationBinderTests.cs b/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/DescriptionCurationBinderTests.cs index bdbe1db8..769212d3 100644 --- a/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/DescriptionCurationBinderTests.cs +++ b/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/DescriptionCurationBinderTests.cs @@ -1,8 +1,14 @@ +using System.Globalization; using System.Text; +using System.Text.Json; +using OpenCode.Sdk.Tools.Generator.Binding; using OpenCode.Sdk.Tools.Generator.Binding.Models; using OpenCode.Sdk.Tools.Generator.Emission; +using OpenCode.Sdk.Tools.Serialization; using OpenCode.Sdk.Tools.Tests.Generator.Binding.Support; using OpenCode.Sdk.Tools.Tests.Support; +using Testably.Abstractions.Testing; +using TUnit.Assertions.Enums; using static OpenCode.Sdk.Tools.Tests.Support.BindingScenarioData; namespace OpenCode.Sdk.Tools.Tests.Generator.Binding; @@ -10,6 +16,76 @@ namespace OpenCode.Sdk.Tools.Tests.Generator.Binding; [ClassDataSource(Shared = SharedType.PerTestSession)] public sealed class DescriptionCurationBinderTests(PinnedBinding pinned) { + [Test] + [Arguments("location", false, "location must be a packages/-relative path with a positive line")] + [Arguments("excerpt", false, "excerpt must be non-empty")] + [Arguments("location", true, "location must be a packages/-relative path with a positive line")] + [Arguments("excerpt", true, "excerpt must be non-empty")] + public async Task Apply_Should_Name_Missing_And_Null_Source_Fields(string field, bool explicitNull, string problem) + { + var document = await BindingTestHost.IngestAsync(new EventDocumentationScenario()); + // The typed base serializes a non-null document with one row and one source. + var json = JsonSerializer.SerializeToNode(EventCuration(Description("Notice", "Data")), ToolJsonContext.Default.GenerationCuration)!; + var source = json["descriptions"]![0]!["sources"]![0]!.AsObject(); + if (explicitNull) + { + source[field] = null; + } + else + { + _ = source.Remove(field); + } + + var fileSystem = new MockFileSystem(); + await fileSystem.File.WriteAllTextAsync("curation.json", json.ToJsonString(), CancellationToken.None); + var exception = await Assert.That(async () => + { + var curation = await new CurationLoader(fileSystem).LoadAsync("curation.json", CancellationToken.None); + _ = new BindingTestHost().Bind(document, Selection("event.get"), curation); + }).Throws(); + + await Assert.That(exception!.Errors).IsEquivalentTo( + [new BindingError(BindingErrorCategory.Curation, "Notice.Data", "description sources[0] " + problem)], CollectionOrdering.Matching); + } + + [Test] + [Arguments("missing", "sources[0] must declare a sources list")] + [Arguments("empty-list", "sources[0] must declare 1 to 4 entries")] + [Arguments("null-entry", "sources[0] must declare a source entry")] + [Arguments("five", "sources[4] exceeds the maximum of 4 entries")] + [Arguments("duplicate", "sources[1] repeats location 'packages/example.ts:1'")] + [Arguments("location", "sources[0] location must be a packages/-relative path with a positive line")] + [Arguments("empty", "sources[0] excerpt must be non-empty")] + [Arguments("multiline", "sources[0] excerpt must be one line")] + [Arguments("short", "sources[0] excerpt must contain 12 to 200 characters")] + [Arguments("long", "sources[0] excerpt must contain 12 to 200 characters")] + public async Task Apply_Should_Refuse_Invalid_Sources(string fault, string problem) + { + var document = await BindingTestHost.IngestAsync(new EventDocumentationScenario()); + var plan = new BindingTestHost().Bind(document, Selection("event.get"), EventCuration()); + var source = new DescriptionSource { Location = "packages/example.ts:1", Excerpt = "An explicit declaration." }; + DescriptionSource? missingSource = null; + IReadOnlyList? sources = fault switch + { + "missing" => null, + "empty-list" => [], + "null-entry" => [missingSource], + "five" => [.. Enumerable.Range(1, 5).Select(index => source with { Location = "packages/example.ts:" + index.ToString(CultureInfo.InvariantCulture) })], + "duplicate" => [source, source], + "location" => [source with { Location = "packages/example.ts:0" }], + "empty" => [source with { Excerpt = "" }], + "multiline" => [source with { Excerpt = "A declaration\ncontinued." }], + "short" => [source with { Excerpt = new string('x', 11) }], + _ => [source with { Excerpt = new string('x', 201) }], + }; + var errors = new BindingErrorCollector(); + + await Assert.That(() => DescriptionCurationBinder.Apply(plan, [Description("Notice", "Data") with { Sources = sources }], errors)).ThrowsNothing(); + + await Assert.That(errors.Snapshot()).IsEquivalentTo( + [new BindingError(BindingErrorCategory.Curation, "Notice.Data", "description " + problem)], CollectionOrdering.Matching); + } + [Test] [Arguments(null, "curation is null")] [Arguments("Type", "curation names no type")] @@ -159,7 +235,15 @@ private static GenerationCuration EventCuration(params DescriptionCuration[] row Curation(Groups("event", RootGroup())) with { Descriptions = rows }; private static DescriptionCuration Description(string type, string? member = null, string summary = "The curated summary.", string? remarks = null) => - new() { Type = type, Member = member, Summary = summary, Remarks = remarks, Reason = "Describe the scenario's generated C# surface." }; + new() + { + Type = type, + Member = member, + Summary = summary, + Remarks = remarks, + Reason = "Describe the scenario's generated C# surface.", + Sources = [new() { Location = "packages/example.ts:1", Excerpt = "An explicit declaration." }], + }; /// A curated summary on a hoisted interface replaces the placeholder and keeps the consume-only remark. [Test] diff --git a/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/Models/DescriptionSourceTests.cs b/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/Models/DescriptionSourceTests.cs new file mode 100644 index 00000000..93055e3d --- /dev/null +++ b/tests/OpenCode.Sdk.Tools.Tests/Generator/Binding/Models/DescriptionSourceTests.cs @@ -0,0 +1,108 @@ +using System.Globalization; +using System.IO.Abstractions; +using OpenCode.Sdk.Tools.Generator.Binding.Models; +using OpenCode.Sdk.Tools.Tests.Support; +using Testably.Abstractions; +using Testably.Abstractions.Testing; +using TUnit.Assertions.Enums; + +namespace OpenCode.Sdk.Tools.Tests.Generator.Binding.Models; + +public sealed class DescriptionSourceTests +{ + private const string Declaration = "An explicit upstream declaration."; + + [Test] + public async Task Sources_Should_Quote_The_Pinned_Upstream_Tree() + { + var fileSystem = new RealFileSystem(); + var root = new RepositoryRoot(fileSystem).Locate(); + var (_, _, curation) = await BindingTestHost.LoadPinnedInputsAsync(); + + await Assert.That(curation.Descriptions).IsNotEmpty(); + await Assert.That(await CheckAsync(fileSystem, root, curation.Descriptions)).IsEmpty(); + } + + [Test] + [Arguments("missing", "file does not exist under external/opencode")] + [Arguments("outside", "excerpt not found within +/-5 lines")] + [Arguments("absent", "excerpt not found within +/-5 lines")] + [Arguments("ordinal", "excerpt not found within +/-5 lines")] + [Arguments("second", "excerpt not found within +/-5 lines")] + [Arguments("lower", null)] + [Arguments("upper", null)] + [Arguments("whitespace", null)] + [Arguments("substring", null)] + public async Task Sources_Should_Refuse_Unproven_Excerpts(string fault, string? problem) + { + var fileSystem = new MockFileSystem(); + var root = fileSystem.Directory.GetCurrentDirectory(); + var path = fileSystem.Path.Combine(root, "external/opencode/packages/example.ts"); + fileSystem.Directory.CreateDirectory(fileSystem.Path.GetDirectoryName(path)!); + if (fault != "missing") + { + var lines = Enumerable.Repeat("Unrelated declaration.", 12).ToArray(); + var index = fault switch { "lower" => 1, "upper" => 5, _ => 6 }; + lines[index] = fault switch + { + "absent" => "Different declaration.", + "ordinal" => Declaration.ToLowerInvariant(), + "whitespace" => "An\t explicit upstream declaration.", + "substring" => "// " + Declaration, + _ => Declaration, + }; + await fileSystem.File.WriteAllLinesAsync(path, lines, CancellationToken.None); + } + + var location = fault switch { "lower" => "packages/example.ts:7", "whitespace" or "substring" or "ordinal" => "packages/example.ts:2", _ => "packages/example.ts:1" }; + var source = new DescriptionSource { Location = location, Excerpt = Declaration }; + DescriptionCuration[] rows = [new() + { + Type = "Notice", Member = "Data", Summary = "The notification data.", Reason = "Verify the evidence oracle.", + Sources = fault == "second" ? [source with { Location = "packages/example.ts:7" }, source] : [source], + }]; + + await Assert.That(await CheckAsync(fileSystem, root, rows)).IsEquivalentTo( + problem is null ? [] : new[] { "Notice.Data: " + location + ": " + problem }, CollectionOrdering.Matching); + } + + private static async Task> CheckAsync(IFileSystem fileSystem, string root, IReadOnlyList rows) + { + var problems = new List(); + foreach (var row in rows) + { + var subject = row.Type + (row.Member is null ? "" : "." + row.Member); + await Assert.That(row.Sources).IsNotNull(); + await Assert.That(row.Sources!).IsNotEmpty(); + // The assertions above require the shape the binder validates before generation. + foreach (var source in row.Sources!) + { + if (source is not { Location: { } location, Excerpt: { } excerpt }) + { + throw new InvalidOperationException("The binder must validate source fields before the evidence oracle."); + } + + var separator = location.LastIndexOf(':', StringComparison.Ordinal); + var path = fileSystem.Path.Combine(root, "external", "opencode", location[..separator]); + var prefix = $"{subject}: {location}: "; + if (!fileSystem.File.Exists(path)) + { + problems.Add(prefix + "file does not exist under external/opencode"); + continue; + } + + var line = int.Parse(location.AsSpan(separator + 1), CultureInfo.InvariantCulture); + var lines = await fileSystem.File.ReadAllLinesAsync(path, CancellationToken.None); + var window = lines.Skip(Math.Max(0, line - 6)).Take(Math.Min(lines.Length, line + 5) - Math.Max(0, line - 6)); + if (!window.Any(candidate => Normalize(candidate).Contains(Normalize(excerpt), StringComparison.Ordinal))) + { + problems.Add(prefix + "excerpt not found within +/-5 lines"); + } + } + } + + return problems; + } + + private static string Normalize(string text) => string.Join(' ', text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)); +} diff --git a/tests/OpenCode.Sdk.Tools.Tests/Generator/Emission/GeneratedDocumentationTests.cs b/tests/OpenCode.Sdk.Tools.Tests/Generator/Emission/GeneratedDocumentationTests.cs index aa422cc3..507bbb7d 100644 --- a/tests/OpenCode.Sdk.Tools.Tests/Generator/Emission/GeneratedDocumentationTests.cs +++ b/tests/OpenCode.Sdk.Tools.Tests/Generator/Emission/GeneratedDocumentationTests.cs @@ -54,8 +54,8 @@ public async Task Summaries_Should_Keep_Shrink_Only_Placeholder_Ceilings_And_Rej var helperFed = summaries.Where(pair => placeholders.Any(pattern => Matches(pair.Value, pattern)) || Matches(pair.Value, @"^(?:Preserves an unknown [a-z0-9 ]+ payload\.$|The [a-z0-9 ]+\. The pinned server's values are the static properties;)")).ToArray(); using var assertions = Assert.Multiple(); - await Assert.That(100m * historical / summaries.Count).IsLessThanOrEqualTo(45.131708m); - await Assert.That(100m * broad / summaries.Count).IsLessThanOrEqualTo(62.614635m); + await Assert.That(100m * historical / summaries.Count).IsLessThanOrEqualTo(44.702440m); + await Assert.That(100m * broad / summaries.Count).IsLessThanOrEqualTo(61.073171m); foreach (var defect in defects) { var offenders = helperFed.Where(pair => Matches(pair.Value, defect)).ToArray(); diff --git a/tools/OpenCode.Sdk.Tools/Generator/Binding/DescriptionCurationBinder.cs b/tools/OpenCode.Sdk.Tools/Generator/Binding/DescriptionCurationBinder.cs index d9e6fb5d..48969e40 100644 --- a/tools/OpenCode.Sdk.Tools/Generator/Binding/DescriptionCurationBinder.cs +++ b/tools/OpenCode.Sdk.Tools/Generator/Binding/DescriptionCurationBinder.cs @@ -1,9 +1,10 @@ +using System.Globalization; using OpenCode.Sdk.Tools.Generator.Binding.Models; namespace OpenCode.Sdk.Tools.Generator.Binding; /// Validates reason-bearing documentation rows against final C# names and binds their plain text. -internal static class DescriptionCurationBinder +internal static partial class DescriptionCurationBinder { public static EmitPlan Apply(EmitPlan plan, IReadOnlyList rows, BindingErrorCollector errors) { @@ -80,9 +81,66 @@ private static void Validate(IReadOnlyDictionary> t errors.Add(BindingErrorCategory.Curation, subject, "description curation must declare a non-empty summary"); } + ValidateSources(row, subject, errors); } } + private static void ValidateSources(DescriptionCuration row, string subject, BindingErrorCollector errors) + { + if (row.Sources is null || row.Sources.Count is 0 or > 4) + { + var problem = row.Sources switch + { + null => "sources[0] must declare a sources list", + { Count: 0 } => "sources[0] must declare 1 to 4 entries", + _ => "sources[4] exceeds the maximum of 4 entries", + }; + errors.Add(BindingErrorCategory.Curation, subject, "description " + problem); + return; + } + + var locations = new HashSet(StringComparer.Ordinal); + for (var index = 0; index < row.Sources.Count; index++) + { + var source = row.Sources[index]; + string? problem = null; + if (source is null) + { + problem = "must declare a source entry"; + } + else if (source.Location is null || !SourceLocation().IsMatch(source.Location)) + { + problem = "location must be a packages/-relative path with a positive line"; + } + else if (!locations.Add(source.Location)) + { + problem = $"repeats location '{source.Location}'"; + } + else if (string.IsNullOrWhiteSpace(source.Excerpt)) + { + problem = "excerpt must be non-empty"; + } + else if (source.Excerpt.Contains('\n', StringComparison.Ordinal) || source.Excerpt.Contains('\r', StringComparison.Ordinal)) + { + problem = "excerpt must be one line"; + } + else if (source.Excerpt.Length is < 12 or > 200) + { + problem = "excerpt must contain 12 to 200 characters"; + } + + if (problem is not null) + { + errors.Add(BindingErrorCategory.Curation, subject, + string.Create(CultureInfo.InvariantCulture, $"description sources[{index}] {problem}")); + } + } + } + + [System.Text.RegularExpressions.GeneratedRegex(@"\Apackages/(?:(?!\.{1,2}(?:/|:))[^/\\:\s]+/)*(?!\.{1,2}:)[^/\\:\s]+:[1-9][0-9]*\z", + System.Text.RegularExpressions.RegexOptions.CultureInvariant, matchTimeoutMilliseconds: Timeout.Infinite)] + private static partial System.Text.RegularExpressions.Regex SourceLocation(); + private static ModelPlan BindModel(ModelPlan model, IReadOnlyDictionary byType) { var documented = model with { Documentation = Bind(model.Name, model.Documentation, byType) }; diff --git a/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionCuration.cs b/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionCuration.cs index 0742bc60..32c37d96 100644 --- a/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionCuration.cs +++ b/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionCuration.cs @@ -19,4 +19,7 @@ internal sealed record DescriptionCuration : IReasonedRow [JsonPropertyName("reason")] public required string Reason { get; init; } + + [JsonPropertyName("sources")] + public IReadOnlyList? Sources { get; init; } } diff --git a/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionSource.cs b/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionSource.cs new file mode 100644 index 00000000..ebc0c237 --- /dev/null +++ b/tools/OpenCode.Sdk.Tools/Generator/Binding/Models/DescriptionSource.cs @@ -0,0 +1,13 @@ +using System.Text.Json.Serialization; + +namespace OpenCode.Sdk.Tools.Generator.Binding.Models; + +/// A quoted upstream declaration supporting documentation, not protocol semantics. +internal sealed record DescriptionSource +{ + [JsonPropertyName("location")] + public string? Location { get; init; } + + [JsonPropertyName("excerpt")] + public string? Excerpt { get; init; } +} diff --git a/tools/curation.json b/tools/curation.json index b787b6b0..6eef9fdd 100644 --- a/tools/curation.json +++ b/tools/curation.json @@ -1,249 +1,1778 @@ { "descriptions": [ { - "type": "SessionMessageAssistant", + "type": "SessionTextDelta", "member": null, - "summary": "One model step's response within a turn. A single prompt can produce several, for example one per round of tool calls; a step that failed keeps its message, with Error set and any partial content.", - "remarks": null, - "reason": "Builders read one assistant message as the whole answer; upstream starts a new assistant message per model step (core/src/session/runner/step.ts)." - }, - { - "type": "SessionMessageAssistant", - "member": "Finish", - "summary": "Why the step ended: stop, length, tool-calls, content-filter, error or unknown; null while the step is still running.", - "remarks": "A step that failed reports error, or content-filter when the provider blocked the response.", - "reason": "Upstream normalises the provider's finish reason in session.step.ended and session.step.failed (core/src/session/message-updater.ts)." + "summary": "A live fragment of assistant text: append its Data.Delta to the text part its Data.AssistantMessageId and Data.Ordinal name.", + "remarks": "Deltas are never stored or replayed; after reconnecting, rely on SessionTextEnded or the session's messages.", + "reason": "Builders kept only deltas and lost text across reconnects; upstream declares stream fragments live-only.", + "sources": [ + { + "location": "packages/schema/src/session-event.ts:403", + "excerpt": " // Stream fragments are live-only; Text.Ended is the replayable full-value boundary." + }, + { + "location": "packages/schema/src/session-event.ts:408", + "excerpt": " assistantMessageID: SessionMessage.ID," + }, + { + "location": "packages/schema/src/session-event.ts:409", + "excerpt": " ordinal: NonNegativeInt," + }, + { + "location": "packages/schema/src/session-event.ts:410", + "excerpt": " delta: Schema.String," + } + ] }, { - "type": "SessionMessageAssistant", - "member": "RawFinish", - "summary": "The provider's own finish-reason string, kept verbatim for diagnostics; it may be null. Use Finish for logic.", + "type": "SessionTextEnded", + "member": null, + "summary": "The end of one assistant text part. It is durable and replayed, and its Data.Text holds the part's complete final text.", "remarks": null, - "reason": "Upstream copies the provider's stop reason unnormalised beside Finish." - }, - { - "type": "SessionMessageAssistant", - "member": "Error", - "summary": "Set when this step failed, for example a provider error, a content filter or an interruption; the message and its partial content stay in the session.", - "remarks": "It is cleared when the step starts again on this same message. When a failure after partial output continues the turn, the continuation is a new message and this one keeps its error.", - "reason": "Builders could not tell a failed turn from a finished one; upstream sets it from session.step.failed and clears it on a retried step.started." - }, - { - "type": "SessionMessageAssistant", - "member": "Retry", - "summary": "Set while a retry of this step is scheduled after a retryable provider error: the attempt number (the first retry is 2), when it runs, and the error that caused it.", - "remarks": "It is cleared when the retry starts or the session goes idle.", - "reason": "Upstream sets it from session.retry.scheduled (core/src/session/runner/retry.ts)." - }, - { - "type": "SessionMessageAssistant", - "member": "Content", - "summary": "The step's output parts in the order they streamed: text, reasoning and tool calls.", + "reason": "Upstream declares Text.Ended the replayable full-value boundary.", + "sources": [ + { + "location": "packages/schema/src/session-event.ts:403", + "excerpt": " // Stream fragments are live-only; Text.Ended is the replayable full-value boundary." + }, + { + "location": "packages/schema/src/session-event.ts:415", + "excerpt": " export const Ended = Event.durable({" + }, + { + "location": "packages/schema/src/session-event.ts:422", + "excerpt": " text: Schema.String," + } + ] + }, + { + "type": "ProviderSettings", + "member": "Timeout", + "summary": "HTTP timeout in milliseconds, or false to disable it.", "remarks": null, - "reason": "The part order is the stream order upstream records." - }, - { - "type": "SessionMessageAssistant", - "member": "Cost", - "summary": "The cost in US dollars of this step alone, computed by the server from the model's configured prices; null until the step finishes, and it may stay null when the step fails.", + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:72", + "excerpt": " /** Time allowed for the whole request, from send until the response completes. Unbounded when unset. */" + } + ] + }, + { + "type": "ProviderSettingsTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. HTTP timeout in milliseconds, or false to disable it.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:72", + "excerpt": " /** Time allowed for the whole request, from send until the response completes. Unbounded when unset. */" + } + ] + }, + { + "type": "ProviderSettings", + "member": "HeaderTimeout", + "summary": "Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:74", + "excerpt": " /** Time allowed for response headers to arrive. */" + }, + { + "location": "packages/ai/src/schema/options.ts:55", + "excerpt": "/** Applied to `headerTimeout` when a request leaves it unset. */" + }, + { + "location": "packages/ai/src/schema/options.ts:56", + "excerpt": "export const DEFAULT_HTTP_TIMEOUT_MS = 300_000" + } + ] + }, + { + "type": "ProviderSettingsHeaderTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:74", + "excerpt": " /** Time allowed for response headers to arrive. */" + }, + { + "location": "packages/ai/src/schema/options.ts:55", + "excerpt": "/** Applied to `headerTimeout` when a request leaves it unset. */" + }, + { + "location": "packages/ai/src/schema/options.ts:56", + "excerpt": "export const DEFAULT_HTTP_TIMEOUT_MS = 300_000" + } + ] + }, + { + "type": "ProviderSettings", + "member": "ChunkTimeout", + "summary": "Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:76", + "excerpt": " /** Time allowed between streamed response chunks once headers have arrived. */" + }, + { + "location": "packages/ai/src/schema/options.ts:59", + "excerpt": " * Applied to `chunkTimeout` when a request leaves it unset. Some providers, such as DeepSeek, have specifically asked" + }, + { + "location": "packages/ai/src/schema/options.ts:62", + "excerpt": "export const DEFAULT_CHUNK_TIMEOUT_MS = 900_000" + } + ] + }, + { + "type": "ProviderSettingsChunkTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:76", + "excerpt": " /** Time allowed between streamed response chunks once headers have arrived. */" + }, + { + "location": "packages/ai/src/schema/options.ts:59", + "excerpt": " * Applied to `chunkTimeout` when a request leaves it unset. Some providers, such as DeepSeek, have specifically asked" + }, + { + "location": "packages/ai/src/schema/options.ts:62", + "excerpt": "export const DEFAULT_CHUNK_TIMEOUT_MS = 900_000" + } + ] + }, + { + "type": "ConfigProviderSettings", + "member": "Timeout", + "summary": "HTTP timeout in milliseconds, or false to disable it.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:72", + "excerpt": " /** Time allowed for the whole request, from send until the response completes. Unbounded when unset. */" + } + ] + }, + { + "type": "ConfigProviderSettingsTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. HTTP timeout in milliseconds, or false to disable it.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:72", + "excerpt": " /** Time allowed for the whole request, from send until the response completes. Unbounded when unset. */" + } + ] + }, + { + "type": "ConfigProviderSettings", + "member": "HeaderTimeout", + "summary": "Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:74", + "excerpt": " /** Time allowed for response headers to arrive. */" + }, + { + "location": "packages/ai/src/schema/options.ts:55", + "excerpt": "/** Applied to `headerTimeout` when a request leaves it unset. */" + }, + { + "location": "packages/ai/src/schema/options.ts:56", + "excerpt": "export const DEFAULT_HTTP_TIMEOUT_MS = 300_000" + } + ] + }, + { + "type": "ConfigProviderSettingsHeaderTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. Time for response headers, in milliseconds; false disables it. The server default is 300,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:74", + "excerpt": " /** Time allowed for response headers to arrive. */" + }, + { + "location": "packages/ai/src/schema/options.ts:55", + "excerpt": "/** Applied to `headerTimeout` when a request leaves it unset. */" + }, + { + "location": "packages/ai/src/schema/options.ts:56", + "excerpt": "export const DEFAULT_HTTP_TIMEOUT_MS = 300_000" + } + ] + }, + { + "type": "ConfigProviderSettings", + "member": "ChunkTimeout", + "summary": "Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:76", + "excerpt": " /** Time allowed between streamed response chunks once headers have arrived. */" + }, + { + "location": "packages/ai/src/schema/options.ts:59", + "excerpt": " * Applied to `chunkTimeout` when a request leaves it unset. Some providers, such as DeepSeek, have specifically asked" + }, + { + "location": "packages/ai/src/schema/options.ts:62", + "excerpt": "export const DEFAULT_CHUNK_TIMEOUT_MS = 900_000" + } + ] + }, + { + "type": "ConfigProviderSettingsChunkTimeout", + "member": null, + "summary": "Represents the timeout setting's alternatives. Time between streamed response chunks in milliseconds; false disables it. The server default is 900,000 ms.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/ai/src/schema/options.ts:51", + "excerpt": "/** Milliseconds for an HTTP timeout, or `false` to disable it. */" + }, + { + "location": "packages/ai/src/schema/options.ts:76", + "excerpt": " /** Time allowed between streamed response chunks once headers have arrived. */" + }, + { + "location": "packages/ai/src/schema/options.ts:59", + "excerpt": " * Applied to `chunkTimeout` when a request leaves it unset. Some providers, such as DeepSeek, have specifically asked" + }, + { + "location": "packages/ai/src/schema/options.ts:62", + "excerpt": "export const DEFAULT_CHUNK_TIMEOUT_MS = 900_000" + } + ] + }, + { + "type": "ConfigInfoMcpTimeout", + "member": "Startup", + "summary": "Maximum time in milliseconds to establish and initialize the MCP server.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/mcp.ts:9", + "excerpt": " description: \"Maximum time in milliseconds to establish and initialize the MCP server.\"," + } + ] + }, + { + "type": "ConfigInfoMcpTimeout", + "member": "Catalog", + "summary": "Maximum time in milliseconds to wait for MCP discovery requests such as tools/list and prompts/list.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/mcp.ts:12", + "excerpt": " description: \"Maximum time in milliseconds to wait for MCP discovery requests such as tools/list and prompts/list.\"," + } + ] + }, + { + "type": "ConfigInfoMcpTimeout", + "member": "Execution", + "summary": "Maximum time in milliseconds to wait for MCP tool and prompt execution.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/mcp.ts:15", + "excerpt": " description: \"Maximum time in milliseconds to wait for MCP tool and prompt execution.\"," + } + ] + }, + { + "type": "ShellInfoTime", + "member": "Completed", + "summary": "Completion time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/shell.ts:31", + "excerpt": " description: \"Completion time in milliseconds since the Unix epoch\"," + } + ] + }, + { + "type": "WebSearchResultTime", + "member": "Published", + "summary": "Publication time in milliseconds since the Unix epoch.", "remarks": null, - "reason": "Builders summed it as a turn total; upstream computes it per step (core/src/session/runner/step.ts)." + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/websearch.ts:30", + "excerpt": " description: \"Publication time in milliseconds since the Unix epoch\"," + } + ] + }, + { + "type": "SessionInfoTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session.ts:46", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionInfoTime", + "member": "Updated", + "summary": "Update time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session.ts:47", + "excerpt": " updated: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionInfoTime", + "member": "Idle", + "summary": "Idle time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session.ts:48", + "excerpt": " idle: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionInfoTime", + "member": "Viewed", + "summary": "Viewed time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session.ts:49", + "excerpt": " viewed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionInfoTime", + "member": "Archived", + "summary": "Archive time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session.ts:50", + "excerpt": " archived: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAgentSelectedTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantReasoningTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:190", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantReasoningTime", + "member": "Completed", + "summary": "Completion time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:191", + "excerpt": " completed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantRetry", + "member": "At", + "summary": "Scheduled retry time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:208", + "excerpt": " at: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:232", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantTime", + "member": "Completed", + "summary": "Completion time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:235", + "excerpt": " completed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantToolTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:171", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantToolTime", + "member": "Ran", + "summary": "Run time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:172", + "excerpt": " ran: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantToolTime", + "member": "Completed", + "summary": "Completion time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:173", + "excerpt": " completed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageIdleTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageLocationSwitchedTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageModelSelectedTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageShellTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:121", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageShellTime", + "member": "Completed", + "summary": "Completion time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:122", + "excerpt": " completed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageSkillTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageSyntheticTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageSystemTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageUserTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:36", + "excerpt": " time: Schema.Struct({ created: DateTimeUtcFromMillis })," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "SessionMessageAssistantTime", + "member": "Streamed", + "summary": "Time the provider response body ended, before tool settlement, in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/session-message.ts:233", + "excerpt": " /** When the provider response body ended, before tool settlement. */" + }, + { + "location": "packages/schema/src/session-message.ts:234", + "excerpt": " streamed: DateTimeUtcFromMillis.pipe(optional)," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "PermissionSavedInfoTime", + "member": "Created", + "summary": "Creation time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/permission-saved.ts:21", + "excerpt": " created: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "PermissionSavedInfoTime", + "member": "Updated", + "summary": "Update time in milliseconds since the Unix epoch.", + "remarks": null, + "reason": "The named schema codec declares the encoded timestamp unit.", + "sources": [ + { + "location": "packages/schema/src/permission-saved.ts:22", + "excerpt": " updated: DateTimeUtcFromMillis," + }, + { + "location": "packages/schema/src/schema.ts:39", + "excerpt": " encode: SchemaGetter.transform((value) => DateTime.toEpochMillis(value))," + } + ] + }, + { + "type": "WorktreeResolvedDurable", + "member": "Seq", + "summary": "Position in one aggregate's durable log. Use only values from durable envelopes or synced markers as after cursors.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/event.ts:17", + "excerpt": " * Position in one aggregate's durable log. Values originate from the durable" + }, + { + "location": "packages/schema/src/event.ts:18", + "excerpt": " * event envelope and synced markers;" + }, + { + "location": "packages/schema/src/event.ts:19", + "excerpt": " * `after` cursors accept only values that came from those sources." + } + ] + }, + { + "type": "WorktreeResolvedDurable", + "member": "Version", + "summary": "Durable schema version of this event type, from the event definition that committed it.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/event.ts:27", + "excerpt": "/** Durable schema version of one event type, from the event definition that committed it. */" + } + ] + }, + { + "type": "EventLogSynced", + "member": "Seq", + "summary": "Captured watermark of this aggregate's durable log; absent when that watermark is empty.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/event-log.ts:9", + "excerpt": " * every event committed at or below this watermark; `seq` is absent when the" + }, + { + "location": "packages/schema/src/event-log.ts:10", + "excerpt": " * captured watermark is empty. Emitted once for the captured watermark." + }, + { + "location": "packages/schema/src/event-log.ts:15", + "excerpt": " seq: optional(Event.Seq)," + }, + { + "location": "packages/schema/src/event.ts:17", + "excerpt": " * Position in one aggregate's durable log. Values originate from the durable" + } + ] + }, + { + "type": "ConfigInfoExperimental", + "member": "SubagentDepth", + "summary": "Maximum subagent nesting depth. Defaults to 1.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/config/experimental.ts:12", + "excerpt": " description: \"Maximum subagent nesting depth. Defaults to 1.\"," + } + ] + }, + { + "type": "ConfigInfoExperimental", + "member": "PortableShellScanner", + "summary": "Enable the experimental portable shell permission scanner. Defaults to false.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/config/experimental.ts:9", + "excerpt": " description: \"Enable the experimental portable shell permission scanner. Defaults to false.\"," + } + ] + }, + { + "type": "ConfigWarming", + "member": "Interval", + "summary": "Idle time between keep-alive requests, as a duration string; default “4 minutes”.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/config/warming.ts:10", + "excerpt": " interval: Schema.DurationFromString.pipe(optional).annotate({" + }, + { + "location": "packages/schema/src/config/warming.ts:11", + "excerpt": " description: 'Idle time between keep-alive requests (default: \"4 minutes\")'," + } + ] + }, + { + "type": "ConfigWarming", + "member": "Duration", + "summary": "Time after the last active request to keep a session warm, as a duration string; default “30 minutes”.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/config/warming.ts:13", + "excerpt": " duration: Schema.DurationFromString.pipe(optional).annotate({" + }, + { + "location": "packages/schema/src/config/warming.ts:14", + "excerpt": " description: 'Time after the last active request to keep a session warm (default: \"30 minutes\")'," + } + ] + }, + { + "type": "TuiToastShowData", + "member": "Duration", + "summary": "Duration in milliseconds.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/schema/src/tui-event.ts:48", + "excerpt": " description: \"Duration in milliseconds\"," + } + ] + }, + { + "type": "ModelInfoTime", + "member": "Released", + "summary": "Release date as a Unix timestamp in milliseconds, or 0 when unknown.", + "remarks": null, + "reason": "The projection omits the declared documentation for this setting.", + "sources": [ + { + "location": "packages/core/src/tool/plugin/opencode.ts:68", + "excerpt": " description: \"Release date as a Unix timestamp in milliseconds, or 0 when unknown.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Commands", + "summary": "Experimental command routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/command.ts:25", + "excerpt": " description: \"Experimental command routes.\"," + } + ] }, { - "type": "SessionMessageAssistant", - "member": "Tokens", - "summary": "The token usage of this step alone; null until the step finishes, and it may stay null when the step fails.", + "type": "CommandsClient", + "member": null, + "summary": "Experimental command routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/command.ts:25", + "excerpt": " description: \"Experimental command routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Events", + "summary": "Experimental event stream routes.", "remarks": null, - "reason": "Per-step usage, as Cost." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/event.ts:55", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"event\", description: \"Experimental event stream routes.\" }))," + } + ] }, { - "type": "SessionTextDelta", + "type": "EventsClient", "member": null, - "summary": "A live fragment of assistant text: append its Data.Delta to the text part its Data.AssistantMessageId and Data.Ordinal name.", - "remarks": "Deltas are never stored or replayed; after reconnecting, rely on SessionTextEnded or the session's messages.", - "reason": "Builders kept only deltas and lost text across reconnects; upstream declares stream fragments live-only (schema/src/session-event.ts)." + "summary": "Experimental event stream routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/event.ts:55", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"event\", description: \"Experimental event stream routes.\" }))," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Forms", + "summary": "Location form routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/form.ts:26", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"form\", description: \"Location form routes.\" }))" + } + ] }, { - "type": "SessionTextDeltaData", - "member": "Delta", - "summary": "The new text to append; it may batch several provider chunks.", + "type": "FormsClient", + "member": null, + "summary": "Location form routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/form.ts:26", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"form\", description: \"Location form routes.\" }))" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "LanguageModels", + "summary": "Experimental model routes.", "remarks": null, - "reason": "Upstream batches deltas about every 100 ms." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/model.ts:43", + "excerpt": " description: \"Experimental model routes.\"," + } + ] }, { - "type": "SessionTextDeltaData", - "member": "Ordinal", - "summary": "The zero-based index of this text part among the text parts of its assistant message; the started, delta and ended events of one part share it.", - "remarks": "Reasoning parts are numbered separately.", - "reason": "Builders took it for a global sequence number." + "type": "LanguageModelsClient", + "member": null, + "summary": "Experimental model routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/model.ts:43", + "excerpt": " description: \"Experimental model routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "PersistentPtys", + "summary": "Prototype persistent PTY routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/persistent-pty.ts:127", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"persistentPty\", description: \"Prototype persistent PTY routes.\" }))" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Plugins", + "summary": "Experimental plugin routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/plugin.ts:59", + "excerpt": " description: \"Experimental plugin routes.\"," + } + ] }, { - "type": "SessionTextEnded", + "type": "PluginsClient", "member": null, - "summary": "The end of one assistant text part. It is durable and replayed, and its Data.Text holds the part's complete final text.", + "summary": "Experimental plugin routes.", "remarks": null, - "reason": "Upstream declares Text.Ended the replayable full-value boundary (schema/src/session-event.ts)." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/plugin.ts:59", + "excerpt": " description: \"Experimental plugin routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Projects", + "summary": "Project routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/project.ts:45", + "excerpt": " description: \"Project routes.\"," + } + ] }, { - "type": "SessionTextEndedData", - "member": "Text", - "summary": "The complete text of the part; it replaces whatever was built up from deltas.", + "type": "ProjectsClient", + "member": null, + "summary": "Project routes.", "remarks": null, - "reason": "Upstream replaces the part's text with it." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/project.ts:45", + "excerpt": " description: \"Project routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Providers", + "summary": "Experimental provider routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/provider.ts:43", + "excerpt": " description: \"Experimental provider routes.\"," + } + ] }, { - "type": "SessionTextEndedData", - "member": "State", - "summary": "Opaque provider metadata for the part, kept so it can be sent back to the provider; do not interpret it.", + "type": "ProvidersClient", + "member": null, + "summary": "Experimental provider routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/provider.ts:43", + "excerpt": " description: \"Experimental provider routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Ptys", + "summary": "Experimental location-scoped PTY routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/pty.ts:146", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"pty\", description: \"Experimental location-scoped PTY routes.\" }))" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "References", + "summary": "Location-scoped project references.", "remarks": null, - "reason": "Upstream stores it for later provider requests only." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/reference.ts:40", + "excerpt": " description: \"Location-scoped project references.\"," + } + ] }, { - "type": "SessionPromptRequest", + "type": "ReferencesClient", "member": null, - "summary": "A prompt for the session's inbox. The call returns as soon as the prompt is stored, before the model runs; follow the turn on the event bus or with the experimental wait.", + "summary": "Location-scoped project references.", "remarks": null, - "reason": "Builders awaited PromptAsync as if it returned the answer; upstream admits the input and schedules the run (protocol/src/groups/session.ts)." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/reference.ts:40", + "excerpt": " description: \"Location-scoped project references.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Rpc", + "summary": "Plugin RPC routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/rpc.ts:30", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"rpc\", description: \"Plugin RPC routes.\" }))" + } + ] }, { - "type": "SessionPromptRequest", - "member": "Id", - "summary": "An optional message id of your own, starting with msg_, which makes the call idempotent: resending it returns the stored item and ignores the new content.", - "remarks": "An id that belongs to another session or another kind of record is a conflict (409).", - "reason": "Upstream's inbox admits an id once (core/src/session/inbox.ts)." + "type": "RpcClient", + "member": null, + "summary": "Plugin RPC routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/rpc.ts:30", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"rpc\", description: \"Plugin RPC routes.\" }))" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Shells", + "summary": "Location-scoped shell command routes.", + "remarks": null, + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/shell.ts:87", + "excerpt": " OpenApi.annotations({ title: \"shell\", description: \"Location-scoped shell command routes.\" })," + } + ] }, { - "type": "SessionPromptRequest", - "member": "Files", - "summary": "Attachments as data: URIs, or file: URIs on the server's own file system, read when the prompt is submitted; at most 20 MiB each.", + "type": "ShellsClient", + "member": null, + "summary": "Location-scoped shell command routes.", "remarks": null, - "reason": "Builders sent client-side paths; upstream reads file: URIs on the server (core/src/session/prompt.ts)." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/shell.ts:87", + "excerpt": " OpenApi.annotations({ title: \"shell\", description: \"Location-scoped shell command routes.\" })," + } + ] }, { - "type": "SessionPromptRequest", + "type": "OpenCodeClient", "member": "Skills", - "summary": "Skills to attach by id; the server puts each skill's text before the prompt, and an unknown id is refused (400).", + "summary": "Experimental skill routes.", "remarks": null, - "reason": "Upstream resolves skills by id at submission." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/skill.ts:25", + "excerpt": " description: \"Experimental skill routes.\"," + } + ] }, { - "type": "SessionPromptRequest", - "member": "Delivery", - "summary": "Steer, the default, puts the prompt into the running turn at its next step; Queue waits for the current turn to end and starts a new turn with it.", + "type": "SkillsClient", + "member": null, + "summary": "Experimental skill routes.", "remarks": null, - "reason": "Upstream's inbox delivery modes (core/src/session/inbox.ts)." - }, - { - "type": "SessionPromptRequest", - "member": "Resume", - "summary": "False stores the prompt without waking the session for it: an idle session leaves it pending until something else wakes it, while a session already running can still take it at its next boundary. The default is true.", + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/skill.ts:25", + "excerpt": " description: \"Experimental skill routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Vcs", + "summary": "Location-scoped version control routes.", "remarks": null, - "reason": "Upstream skips scheduling the run when resume is false." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/vcs.ts:128", + "excerpt": " description: \"Location-scoped version control routes.\"," + } + ] }, { - "type": "SessionCreateRequest", + "type": "VcsClient", "member": null, - "summary": "A new session, or, when Id names an existing one, that session returned unchanged.", + "summary": "Location-scoped version control routes.", "remarks": null, - "reason": "Upstream's create is idempotent on the id (core/src/session.ts)." - }, - { - "type": "SessionCreateRequest", - "member": "Id", - "summary": "An optional session id of your own; when a session with it exists, that session is returned and the other members are ignored.", + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/vcs.ts:128", + "excerpt": " description: \"Location-scoped version control routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Websearch", + "summary": "Location-scoped web search routes.", "remarks": null, - "reason": "As the type summary." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/websearch.ts:44", + "excerpt": " description: \"Location-scoped web search routes.\"," + } + ] }, { - "type": "SessionCreateRequest", - "member": "ParentId", - "summary": "Makes this a child session, such as a subagent's, of an existing parent. The child always works in the parent's location and inherits its metadata and permissions unless you set them.", - "remarks": "Agent and model are not inherited.", - "reason": "Upstream's create handler drops the location of a child and copies the parent's (server/src/handlers/session.ts)." - }, - { - "type": "SessionCreateRequest", - "member": "Agent", - "summary": "The agent to use. When it is absent, the server chooses its default agent each time the session runs a step.", + "type": "WebsearchClient", + "member": null, + "summary": "Location-scoped web search routes.", "remarks": null, - "reason": "Upstream stores no agent when none is given (core/src/agent.ts)." - }, - { - "type": "SessionCreateRequest", - "member": "Model", - "summary": "The model to use. When it is absent, the server chooses its default model each time the session runs a step; an unavailable model is reported only when the session runs.", + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/websearch.ts:44", + "excerpt": " description: \"Location-scoped web search routes.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Worktrees", + "summary": "Project-based worktree management routes.", "remarks": null, - "reason": "Builders expected create to validate the model; upstream resolves it per turn (core/src/session/runner/model.ts)." + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/worktree.ts:78", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"worktree\", description: \"Project-based worktree management routes.\" }))" + } + ] }, { - "type": "SessionCreateRequest", - "member": "Location", - "summary": "The directory the session works in; the server's working directory when absent. It is ignored when ParentId is set.", + "type": "WorktreesClient", + "member": null, + "summary": "Project-based worktree management routes.", "remarks": null, - "reason": "Upstream defaults to the process directory and gives a child its parent's location." - }, - { - "type": "SessionCreateRequest", - "member": "Permissions", - "summary": "Session permission rules, checked after the agent's own; the last rule that matches wins, so they override the agent. Anything no rule matches asks.", + "reason": "Describe the upstream route group exposed by this family.", + "sources": [ + { + "location": "packages/protocol/src/groups/worktree.ts:78", + "excerpt": " .annotateMerge(OpenApi.annotations({ title: \"worktree\", description: \"Project-based worktree management routes.\" }))" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Agents", + "summary": "Lists registered agents and retrieves an agent by identifier.", "remarks": null, - "reason": "Upstream appends session rules after the agent's (core/src/permission.ts)." - }, - { - "type": "SessionExecutionStarted", + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/agent.ts:10", + "excerpt": " HttpApiEndpoint.get(\"agent.list\", \"/api/agent\", {" + }, + { + "location": "packages/protocol/src/groups/agent.ts:24", + "excerpt": " HttpApiEndpoint.get(\"agent.get\", \"/api/agent/:agentID\", {" + } + ] + }, + { + "type": "AgentsClient", "member": null, - "summary": "The server began working on the session after it was woken while idle. When that work settles, exactly one of SessionExecutionSucceeded, SessionExecutionFailed or SessionExecutionInterrupted follows, however many prompts arrive meanwhile; a server that crashes mid-work publishes none.", + "summary": "Lists registered agents and retrieves an agent by identifier.", "remarks": null, - "reason": "Upstream publishes one terminal observation per busy period (core/src/session/execution.ts)." - }, - { - "type": "SessionExecutionSucceeded", + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/agent.ts:10", + "excerpt": " HttpApiEndpoint.get(\"agent.list\", \"/api/agent\", {" + }, + { + "location": "packages/protocol/src/groups/agent.ts:24", + "excerpt": " HttpApiEndpoint.get(\"agent.get\", \"/api/agent/:agentID\", {" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Config", + "summary": "Reads the location's configuration documents and lists shells available for terminal and agent execution.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/config.ts:30", + "excerpt": " description: \"Return shells available to terminal and agent execution.\"," + }, + { + "location": "packages/protocol/src/groups/config.ts:19", + "excerpt": " \"Return configuration documents and discovery sources for the requested location, from lowest to highest priority.\"," + } + ] + }, + { + "type": "ConfigClient", "member": null, - "summary": "The execution finished the work it took on and the session went idle. Prompts it did not take, such as queued ones, can still be pending.", + "summary": "Reads the location's configuration documents and lists shells available for terminal and agent execution.", "remarks": null, - "reason": "The turn-ending event builders need to wait on." + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/config.ts:30", + "excerpt": " description: \"Return shells available to terminal and agent execution.\"," + }, + { + "location": "packages/protocol/src/groups/config.ts:19", + "excerpt": " \"Return configuration documents and discovery sources for the requested location, from lowest to highest priority.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Credentials", + "summary": "Lists, stores, labels, activates and removes integration credentials.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/credential.ts:6", + "excerpt": "export const CredentialGroup = HttpApiGroup.make(\"server.credential\")" + } + ] }, { - "type": "SessionExecutionFailed", + "type": "CredentialsClient", "member": null, - "summary": "The session stopped on an error and went idle; its Data.Error says why.", - "remarks": "It is also published when a turn interrupted by repeated restarts can no longer be resumed.", - "reason": "Upstream publishes it from the run coordinator and from restart recovery (core/src/session/execution/restart.ts)." - }, - { - "type": "SessionExecutionInterrupted", + "summary": "Lists, stores, labels, activates and removes integration credentials.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/credential.ts:6", + "excerpt": "export const CredentialGroup = HttpApiGroup.make(\"server.credential\")" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Debug", + "summary": "Lists loaded locations and evicts their cached services.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/debug.ts:14", + "excerpt": " description: \"List locations currently loaded by the server.\"," + }, + { + "location": "packages/protocol/src/groups/debug.ts:28", + "excerpt": " description: \"Dispose the requested location's cached services so its next use boots them fresh.\"," + } + ] + }, + { + "type": "DebugClient", "member": null, - "summary": "The session's work stopped before it finished; its Data.Reason says why.", - "remarks": "With the shutdown reason the turn is not over: the server keeps it marked in progress, and a server that resumes work after it restarts picks it up again with a new SessionExecutionStarted. A turn that cannot be resumed, or has been resumed too often, ends with SessionExecutionFailed.", - "reason": "Builders treated every interrupt as the end of a turn; upstream resumes a shutdown interrupt (core/src/session/execution/restart.ts)." - }, - { - "type": "PtyCreateRequest", - "member": "Command", - "summary": "The program to run, an executable rather than a command line. When it is absent the server picks a shell: the configured shell, then $SHELL, then a per-platform fallback.", - "remarks": "The fallback is, on Windows, the first of pwsh, powershell and Git Bash that is found, otherwise %COMSPEC%, or cmd.exe when COMSPEC is unset; /bin/zsh on macOS; and bash on PATH, or else /bin/sh, elsewhere. A configured shell that is not executable skips $SHELL and goes straight to the fallback. PowerShell starts with no added arguments, so its profile loads; pass -NoProfile in Args for a clean one.", - "reason": "Builders could not predict which shell a PTY gets; upstream's resolver order (core/src/pty.ts, core/src/shell/select.ts)." - }, - { - "type": "PtyCreateRequest", - "member": "Args", - "summary": "Arguments passed as they are to the program, with no shell parsing.", - "remarks": "When the program is bash, dash, fish, ksh, sh or zsh, the server appends -l after these arguments, so bash -c \"cmd\" receives -l as $0; the returned info shows it.", - "reason": "Upstream appends the login flag for login shells (core/src/pty.ts)." - }, - { - "type": "ExperimentalSessionStatsRequest", - "member": "From", - "summary": "The start of the range, inclusive, in milliseconds since the Unix epoch. Unset, the range starts at the earliest message.", + "summary": "Lists loaded locations and evicts their cached services.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/debug.ts:14", + "excerpt": " description: \"List locations currently loaded by the server.\"," + }, + { + "location": "packages/protocol/src/groups/debug.ts:28", + "excerpt": " description: \"Dispose the requested location's cached services so its next use boots them fresh.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Experimental", + "summary": "Provides experimental generation, session, integration, MCP, filesystem, configuration and migration operations.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/generate.ts:8", + "excerpt": " HttpApiEndpoint.post(\"generate.text\", \"/api/experimental/generate\", {" + }, + { + "location": "packages/protocol/src/groups/session.ts:202", + "excerpt": " HttpApiEndpoint.get(\"session.stats\", \"/api/experimental/session/stats\", {" + }, + { + "location": "packages/protocol/src/groups/integration.ts:46", + "excerpt": " HttpApiEndpoint.post(\"integration.wellknown.add\", \"/api/experimental/integration/wellknown\", {" + }, + { + "location": "packages/protocol/src/groups/mcp.ts:24", + "excerpt": " HttpApiEndpoint.put(\"mcp.add\", \"/api/experimental/mcp/:server\", {" + } + ] + }, + { + "type": "ExperimentalClient", + "member": null, + "summary": "Provides experimental generation, session, integration, MCP, filesystem, configuration and migration operations.", "remarks": null, - "reason": "The wire says only 'from'; upstream compares it with message times in epoch milliseconds and treats it as inclusive (core/src/session/stats.ts)." + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/generate.ts:8", + "excerpt": " HttpApiEndpoint.post(\"generate.text\", \"/api/experimental/generate\", {" + }, + { + "location": "packages/protocol/src/groups/session.ts:202", + "excerpt": " HttpApiEndpoint.get(\"session.stats\", \"/api/experimental/session/stats\", {" + }, + { + "location": "packages/protocol/src/groups/integration.ts:46", + "excerpt": " HttpApiEndpoint.post(\"integration.wellknown.add\", \"/api/experimental/integration/wellknown\", {" + }, + { + "location": "packages/protocol/src/groups/mcp.ts:24", + "excerpt": " HttpApiEndpoint.put(\"mcp.add\", \"/api/experimental/mcp/:server\", {" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "FileSystem", + "summary": "Reads file content and lists or finds entries at the requested location.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/fs.ts:33", + "excerpt": " HttpApiEndpoint.get(\"fs.read\", \"/api/fs/read/*\", {" + }, + { + "location": "packages/protocol/src/groups/fs.ts:49", + "excerpt": " HttpApiEndpoint.get(\"fs.list\", \"/api/fs/list\", {" + }, + { + "location": "packages/protocol/src/groups/fs.ts:65", + "excerpt": " HttpApiEndpoint.get(\"fs.find\", \"/api/fs/find\", {" + } + ] + }, + { + "type": "FileSystemClient", + "member": null, + "summary": "Reads file content and lists or finds entries at the requested location.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/fs.ts:33", + "excerpt": " HttpApiEndpoint.get(\"fs.read\", \"/api/fs/read/*\", {" + }, + { + "location": "packages/protocol/src/groups/fs.ts:49", + "excerpt": " HttpApiEndpoint.get(\"fs.list\", \"/api/fs/list\", {" + }, + { + "location": "packages/protocol/src/groups/fs.ts:65", + "excerpt": " HttpApiEndpoint.get(\"fs.find\", \"/api/fs/find\", {" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Integrations", + "summary": "Discovers integrations and runs key, external, OAuth or command authentication flows.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/integration.ts:14", + "excerpt": "export const IntegrationGroup = HttpApiGroup.make(\"server.integration\")" + } + ] }, { - "type": "ExperimentalSessionStatsRequest", - "member": "To", - "summary": "The end of the range, exclusive, in milliseconds since the Unix epoch. Unset, the range ends now.", + "type": "IntegrationsClient", + "member": null, + "summary": "Discovers integrations and runs key, external, OAuth or command authentication flows.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/integration.ts:14", + "excerpt": "export const IntegrationGroup = HttpApiGroup.make(\"server.integration\")" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "McpServers", + "summary": "Lists MCP servers and discovers their resources and resource templates.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/mcp.ts:19", + "excerpt": " description: \"Retrieve configured MCP servers and their connection status.\"," + }, + { + "location": "packages/protocol/src/groups/mcp.ts:99", + "excerpt": " description: \"Retrieve resources and resource templates from connected MCP servers.\"," + } + ] + }, + { + "type": "McpServersClient", + "member": null, + "summary": "Lists MCP servers and discovers their resources and resource templates.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/mcp.ts:19", + "excerpt": " description: \"Retrieve configured MCP servers and their connection status.\"," + }, + { + "location": "packages/protocol/src/groups/mcp.ts:99", + "excerpt": " description: \"Retrieve resources and resource templates from connected MCP servers.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Permissions", + "summary": "Lists location permission requests and saved permissions, and removes saved permissions.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/permission.ts:32", + "excerpt": " description: \"Retrieve pending permission requests for a location.\"," + }, + { + "location": "packages/protocol/src/groups/permission.ts:44", + "excerpt": " description: \"Retrieve saved permissions, optionally filtered by project.\"," + }, + { + "location": "packages/protocol/src/groups/permission.ts:56", + "excerpt": " description: \"Remove a saved permission by ID.\"," + } + ] + }, + { + "type": "PermissionsClient", + "member": null, + "summary": "Lists location permission requests and saved permissions, and removes saved permissions.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/permission.ts:32", + "excerpt": " description: \"Retrieve pending permission requests for a location.\"," + }, + { + "location": "packages/protocol/src/groups/permission.ts:44", + "excerpt": " description: \"Retrieve saved permissions, optionally filtered by project.\"," + }, + { + "location": "packages/protocol/src/groups/permission.ts:56", + "excerpt": " description: \"Remove a saved permission by ID.\"," + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Server", + "summary": "Reads server identity and readiness and creates or consumes pairing links.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/server.ts:49", + "excerpt": " description: \"Return the server identity, connection URLs, paths, and readiness status.\"," + }, + { + "location": "packages/protocol/src/groups/server.ts:54", + "excerpt": " HttpApiEndpoint.post(\"server.pair\", \"/api/pair\", {" + }, + { + "location": "packages/protocol/src/groups/server.ts:65", + "excerpt": " HttpApiEndpoint.get(\"server.connect\", PAIRING_CONNECT_PATH, {" + } + ] + }, + { + "type": "ServerClient", + "member": null, + "summary": "Reads server identity and readiness and creates or consumes pairing links.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/server.ts:49", + "excerpt": " description: \"Return the server identity, connection URLs, paths, and readiness status.\"," + }, + { + "location": "packages/protocol/src/groups/server.ts:54", + "excerpt": " HttpApiEndpoint.post(\"server.pair\", \"/api/pair\", {" + }, + { + "location": "packages/protocol/src/groups/server.ts:65", + "excerpt": " HttpApiEndpoint.get(\"server.connect\", PAIRING_CONNECT_PATH, {" + } + ] + }, + { + "type": "OpenCodeClient", + "member": "Sessions", + "summary": "Creates and lists sessions and opens session handles for prompts, messages, forms and execution control.", + "remarks": null, + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/session.ts:180", + "excerpt": " HttpApiGroup.make(\"server.session\")" + }, + { + "location": "packages/protocol/src/groups/session.ts:396", + "excerpt": " HttpApiEndpoint.post(\"session.prompt\", \"/api/session/:sessionID/prompt\", {" + }, + { + "location": "packages/protocol/src/groups/message.ts:68", + "excerpt": " HttpApiEndpoint.get(\"session.messages\", \"/api/session/:sessionID/message\", {" + }, + { + "location": "packages/protocol/src/groups/permission.ts:63", + "excerpt": " HttpApiEndpoint.post(\"session.permission.create\", \"/api/session/:sessionID/permission\", {" + } + ] + }, + { + "type": "SessionsClient", + "member": null, + "summary": "Creates and lists sessions and opens session handles for prompts, messages, forms and execution control.", "remarks": null, - "reason": "The wire says only 'to'; upstream compares it with message times in epoch milliseconds, defaults it to Date.now() and treats it as exclusive (core/src/session/stats.ts)." + "reason": "Describe the purpose of the generated family rather than repeat its name.", + "sources": [ + { + "location": "packages/protocol/src/groups/session.ts:180", + "excerpt": " HttpApiGroup.make(\"server.session\")" + }, + { + "location": "packages/protocol/src/groups/session.ts:396", + "excerpt": " HttpApiEndpoint.post(\"session.prompt\", \"/api/session/:sessionID/prompt\", {" + }, + { + "location": "packages/protocol/src/groups/message.ts:68", + "excerpt": " HttpApiEndpoint.get(\"session.messages\", \"/api/session/:sessionID/message\", {" + }, + { + "location": "packages/protocol/src/groups/permission.ts:63", + "excerpt": " HttpApiEndpoint.post(\"session.permission.create\", \"/api/session/:sessionID/permission\", {" + } + ] } ], "sessionScopedEvent": {