@github/copilot-sdk 1.0.29-preview.1 → 1.0.29-preview.3

package/dist/generated/rpc.d.ts

@@ -1081,6 +1081,8 @@ export type CatalogCapability =
  | "catalog-search-credential-required"
 /** Captures the exact existing native session, account, host and connection for authenticated catalogue search, selection and planning. Requires catalog-search-credential-required; does not grant installation or create a session. */
  | "catalog-search-session-bound"
+/** Understands initial-page official-product recommendations for a full task and product with fixed pageSize 10. Requires session-bound, credential-required catalogue support. No anonymous retry, broad-search fallback or continuation. Authentication uses the selected GitHub.com user credential; successful capability negotiation does not establish service acceptance. */
+ | "catalog-recommend"
 /** Understands effect-free preparation, exact human-confirmed apply and owned removal for fully resolved personal remote MCP choices without supplied inputs or configured secrets. Advertised only when the real producer and lower owned admission are linked; requires original connection and bound session authority for new work. */
  | "mcp-confirmed-remote-installation"
 /** Extends mcp-confirmed-remote-installation to declared non-secret header and URL values and receipt-owned header secrets for personal remote MCP choices. Requires mcp-confirmed-remote-installation and bound session authority. Secret values are written only to the reviewed backend after confirmation and are never returned; package and stdio choices remain unsupported. Advertised only when owned secret effects and owned secret activation are linked. */
@@ -1211,6 +1213,8 @@ export type CatalogInvalidRequestField =
 "policySessionId"
 /** The search query was empty or longer than permitted. */
  | "query"
+/** The requested recommendation product was missing, blank or longer than permitted. */
+ | "product"
 /** The requested result count fell outside its permitted range. */
  | "limit"
 /** The requested candidate kinds were empty or contained a duplicate. */
@@ -1714,7 +1718,7 @@ export type CatalogSearchTotalCountRelation =
 /** No exact/full-query or lower-bound guarantee is available. */
 "unknown";
 /**
- * Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+ * Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "CatalogSearchResult".
@@ -5701,6 +5705,18 @@ export type SessionLimitPredictionUnavailableReason =
  */
 /** @experimental */
 export type SessionListEntry = LocalSessionMetadataValue | RemoteSessionMetadataValue;
+/**
+ * Peer boundary evaluated in the process hosting the native session.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementScope".
+ */
+/** @experimental */
+export type SessionManagementScope = 
+/** Eligible local peers sharing the resolved configuration directory. */
+"all"
+/** Only peers hosted in this native runtime process. */
+ | "in-process";
 /**
  * Public-facing workspace metadata for this session, or null if the session has no associated workspace. Excludes runtime-internal fields (GitHub IDs, summary count, internal flags).
  *
@@ -5874,7 +5890,7 @@ export type SessionsOpenProgressStep =
 "load-session"
 /** Validating that the local repository matches the remote session's repository. */
  | "validate-repo"
-/** Checking the local working tree for uncommitted changes that would block the handoff. */
+/** Checking the local working tree for uncommitted changes, which stay in place and are carried onto the checked-out branch. */
  | "check-changes"
 /** Checking out the branch associated with the remote session in the local working tree. */
  | "checkout-branch"
@@ -8716,7 +8732,7 @@ export interface AgentsDiscoverRequest {
      */
     agentDirectories?: string[];
     /**
-     * Optional list of project directory paths to scan for project-scoped agents. When omitted or empty, only user/plugin/remote-independent agents are returned (no project scan).
+     * Optional list of project directory paths to scan for project-scoped agents. When omitted or empty, no project is scanned: user-level and globally enabled plugin agents are still returned, but agents of a plugin enabled only in a repository's settings are not.
      */
     projectPaths?: string[];
     /**
@@ -9170,6 +9186,19 @@ export interface AutopilotObjectiveState {
      */
     creditLimit?: AutopilotObjectiveCreditLimit;
 }
+/**
+ * Client-resolved preference for retaining autopilot mode after objective completion or pause.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "AutopilotObjectiveSetStayInAutopilotRequest".
+ */
+/** @experimental */
+export interface AutopilotObjectiveSetStayInAutopilotRequest {
+    /**
+     * Whether an objective's requested return to interactive mode is suppressed.
+     */
+    value: boolean;
+}
 /** @experimental */
 export interface AutopilotOptions {
     /**
@@ -11484,6 +11513,31 @@ export interface CatalogPolicyRejectedError {
      */
     message: string;
 }
+/**
+ * Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogRecommendRequest".
+ */
+/** @experimental */
+export interface CatalogRecommendRequest {
+    /**
+     * Required contract, including catalog-recommend, catalog-search-session-bound and catalog-search-credential-required.
+     */
+    contract: CatalogClientContract;
+    /**
+     * Existing attached local session whose account, host and connection own the candidate references. Never creates or resumes a session.
+     */
+    policySessionId: string;
+    /**
+     * Full original task, including action, account, output and host requirements. Forwarded without trimming or rewriting and excluded from telemetry.
+     */
+    query: string;
+    /**
+     * Requested product. Agent Finder resolves aliases and applies its versioned official-product approvals before limiting results.
+     */
+    product: string;
+}
 /**
  * A computed Skill install plan. Nothing has been applied.
  *
@@ -17740,6 +17794,43 @@ export interface ManagedPluginRetryEntry {
      */
     error?: string;
 }
+/**
+ * An opted-in local session, reported by its live owner.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ManagedSessionInfo".
+ */
+/** @experimental */
+export interface ManagedSessionInfo {
+    /**
+     * Live peer's session identifier.
+     */
+    sessionId: string;
+    /**
+     * Human-readable peer name.
+     */
+    name: string;
+    /**
+     * Peer's current working directory.
+     */
+    cwd: string;
+    /**
+     * Peer's local session-state directory containing events.jsonl, when known.
+     */
+    sessionStatePath?: string;
+    /**
+     * Either idle or busy. A busy session may still accept messages.
+     */
+    state: string;
+    /**
+     * Peer's selected model, when known.
+     */
+    model?: string;
+    /**
+     * The session that created this root through session management, if any.
+     */
+    parentSessionId?: string;
+}
 /**
  * Lock state and provenance of one managed setting.
  *
@@ -23901,6 +23992,24 @@ export interface PermissionRulesSet {
      */
     denied: PermissionRule[];
 }
+/**
+ * Available permission modes, derived from current session policy.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "PermissionsCapabilities".
+ */
+/** @experimental */
+export interface PermissionsCapabilities {
+    /**
+     * Whether LLM-assisted approval is enabled for this session.
+     */
+    assistedApproval: boolean;
+    /**
+     * Whether managed policy currently permits unconditional approval.
+     * Stays true while managed policy is still resolving.
+     */
+    bypassPermissions: boolean;
+}
 /**
  * No parameters.
  *
@@ -25286,6 +25395,19 @@ export interface ProviderSessionToken {
      */
     expiresAt?: string;
 }
+/**
+ * Credential-free provider configuration status for the selected model.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ProviderStatus".
+ */
+/** @experimental */
+export interface ProviderStatus {
+    /**
+     * Whether the selected model uses a custom provider instead of requiring GitHub authentication.
+     */
+    hasCustomProvider: boolean;
+}
 /**
  * Authoritative BYOK provider and model registry snapshot to apply atomically to the session.
  *
@@ -29063,6 +29185,282 @@ export interface SessionManagedSettings {
      */
     permissions?: SessionManagedPermissions;
 }
+/**
+ * Closes one live opted-in descendant without deleting its saved history or closing its children.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementCloseRequest".
+ */
+/** @experimental */
+export interface SessionManagementCloseRequest {
+    /**
+     * Live created descendant whose owning host should close it.
+     */
+    targetSessionId: string;
+}
+/**
+ * Completion of the existing non-deleting close lifecycle.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementCloseResult".
+ */
+/** @experimental */
+export interface SessionManagementCloseResult {
+    /**
+     * True after the owning host has completed the existing session-close lifecycle.
+     */
+    closed: boolean;
+}
+/**
+ * Updates the session's live policy without changing persistent host settings.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementConfigureRequest".
+ */
+/** @experimental */
+export interface SessionManagementConfigureRequest {
+    /**
+     * Expected workspace for host activation. Required when enabling an interactive CLI session.
+     */
+    cwd?: string;
+    /**
+     * Enabling resets all session management operations to enabled, then applies overrides.
+     */
+    enabled?: boolean;
+    /**
+     * Peer boundary. Preserved when the master switch changes.
+     */
+    scope?: SessionManagementScope;
+    /**
+     * Individual tool overrides, applied after the master switch.
+     */
+    tools?: SessionManagementToolOverrides;
+    /**
+     * Bind creation to this SDK connection's sessionManagement.create callback.
+     */
+    hasCreateHandler?: boolean;
+}
+/**
+ * Per-operation overrides for an enabled session management policy.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementToolOverrides".
+ */
+/** @experimental */
+export interface SessionManagementToolOverrides {
+    /**
+     * Allow discovering eligible peer sessions.
+     */
+    list?: boolean;
+    /**
+     * Allow requesting an independent session from the owning host.
+     */
+    create?: boolean;
+    /**
+     * Allow delivering peer text to another eligible session.
+     */
+    message?: boolean;
+    /**
+     * Allow closing this session's live created descendants.
+     */
+    close?: boolean;
+}
+/**
+ * Host callback. The host owns workspace records, UI, approval routing and cleanup.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementCreateHostRequest".
+ */
+/** @experimental */
+export interface SessionManagementCreateHostRequest {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * The originating session; the host must not escalate its permissions.
+     */
+    parentSessionId: string;
+    /**
+     * Runtime-allocated identity. The host must create a fresh session with this exact ID.
+     */
+    newSessionId: string;
+    /**
+     * The new session must use this workspace and configuration directory.
+     */
+    cwd: string;
+    /**
+     * Parent's resolved configuration directory, which the host must preserve.
+     */
+    configDir: string;
+    /**
+     * Must not be broadened by the creating host.
+     */
+    permissionMode: PermissionMode;
+    /**
+     * Effective model to apply when creating the child.
+     */
+    model?: string;
+    /**
+     * Provider owning the effective model, when specified.
+     */
+    providerId?: string;
+    /**
+     * Effective reasoning effort, when specified.
+     */
+    reasoningEffort?: string;
+    /**
+     * Effective model-supported context tier, when specified.
+     */
+    contextTier?: ContextTier;
+    /**
+     * The host must preserve the parent's current model restrictions.
+     */
+    allowedModels?: string[];
+    /**
+     * Optional short name supplied for the independent session.
+     */
+    name?: string;
+}
+/**
+ * Requests a separate session. Omitted launch options inherit the caller's current configuration.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementCreateRequest".
+ */
+/** @experimental */
+export interface SessionManagementCreateRequest {
+    /**
+     * Initial task, delivered as peer text after successful creation.
+     */
+    prompt: string;
+    /**
+     * Optional short name for the independent session.
+     */
+    name?: string;
+    /**
+     * Absolute working directory. Defaults to the parent's current directory.
+     */
+    cwd?: string;
+    /**
+     * Optional model override; omission uses the parent's current model.
+     */
+    model?: string;
+    /**
+     * Optional effort supported by the selected model.
+     */
+    reasoningEffort?: string;
+    /**
+     * Uses the selected model's supported default or long-context tier, not an arbitrary token count.
+     */
+    contextTier?: ContextTier;
+}
+/**
+ * Identifies a session owned and supervised by the creating host.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementCreateResult".
+ */
+/** @experimental */
+export interface SessionManagementCreateResult {
+    /**
+     * Runtime-allocated identifier of the newly created session.
+     */
+    sessionId: string;
+}
+/**
+ * Lists opted-in local peers. The caller is omitted.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementListRequest".
+ */
+/** @experimental */
+export interface SessionManagementListRequest {
+    /**
+     * Optional exact working-directory filter.
+     */
+    cwd?: string;
+}
+/**
+ * Eligible live peers reported by their owning runtimes.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementListResult".
+ */
+/** @experimental */
+export interface SessionManagementListResult {
+    /**
+     * Matching peers, excluding the caller.
+     */
+    sessions: ManagedSessionInfo[];
+}
+/**
+ * Sends peer text, never human approval, to another opted-in session.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementMessageRequest".
+ */
+/** @experimental */
+export interface SessionManagementMessageRequest {
+    /**
+     * Eligible live peer that should receive the message.
+     */
+    targetSessionId: string;
+    /**
+     * Nonempty UTF-8 text, at most 16 KiB.
+     */
+    message: string;
+}
+/**
+ * Acceptance is not a completed turn or a reply.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementMessageResult".
+ */
+/** @experimental */
+export interface SessionManagementMessageResult {
+    /**
+     * True when the destination has accepted the peer message.
+     */
+    accepted: boolean;
+    /**
+     * Destination title captured by the receiving runtime at message admission.
+     */
+    targetSessionName?: string;
+}
+/**
+ * Opt-in policy for local session management.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionManagementPolicy".
+ */
+/** @experimental */
+export interface SessionManagementPolicy {
+    /**
+     * Master switch. Off by default.
+     */
+    enabled: boolean;
+    /**
+     * Discovery and direct access boundary. Defaults to all eligible local peers.
+     */
+    scope: SessionManagementScope;
+    /**
+     * Allow listing opted-in sessions in this configuration directory.
+     */
+    list: boolean;
+    /**
+     * Allow requesting a new session from the owning host.
+     */
+    create: boolean;
+    /**
+     * Allow sending a peer message to another opted-in session.
+     */
+    message: boolean;
+    /**
+     * Allow closing sessions created by this session or its descendants. On by default.
+     */
+    close: boolean;
+}
 /**
  * Records which IDE the host is connected to, or clears it.
  *
@@ -38445,9 +38843,17 @@ export declare function createServerRpc(connection: MessageConnection): {
          *
          * @param params A bounded catalog search. Both the query length and the result count are capped by the schema so a caller cannot request an unbounded scan.
          *
-         * @returns Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+         * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
          */
         search: (params: CatalogSearchRequest) => Promise<CatalogSearchResult>;
+        /**
+         * Requests the initial page of at most ten official-product recommendations for a complete task and product, bound to an existing attached local session. Requires catalog-recommend, catalog-search-session-bound and catalog-search-credential-required. Uses the selected GitHub.com user credential on the fixed Agent Finder recommendations route; successful capability negotiation does not establish service acceptance. Returns the existing inert catalog candidates and retained install references with the typed catalog refusal union. No anonymous retry, unfiltered search fallback or continuation is performed. Server-owned product approvals establish provenance, not task suitability. Read-only: nothing is installed, configured or persisted.
+         *
+         * @param params Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+         *
+         * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
+         */
+        recommend: (params: CatalogRecommendRequest) => Promise<CatalogSearchResult>;
         /**
          * Retrieves one saved feed by its opaque ID, optionally filtered by trust tier. Requires catalog-feeds and catalog-search-credential-required, and uses the same authority, credential policy, optional session binding and candidate projection as catalog.search, so available entries are the same inert candidates, with the same installability, handles and display metadata, and install through the same confirmed flows. Entries keep the feed's order; an entry the runtime cannot present is returned as unavailable with a reason rather than failing the feed. No anonymous retry. Read-only: nothing is installed, configured, or persisted.
          *
@@ -38805,6 +39211,49 @@ export declare function createServerRpc(connection: MessageConnection): {
 };
 /** Create typed session-scoped RPC methods. */
 export declare function createSessionRpc(connection: MessageConnection, sessionId: string): {
+    /** @experimental */
+    management: {
+        /**
+         * Updates opt-in session management policy live. Enabling the master enables all tools before applying individual overrides. Opt-in is scoped to the session's configuration directory.
+         *
+         * @param params Updates the session's live policy without changing persistent host settings.
+         *
+         * @returns Opt-in policy for local session management.
+         */
+        configure: (params: SessionManagementConfigureRequest) => Promise<SessionManagementPolicy>;
+        /**
+         * Lists other live, opted-in sessions in the same configuration directory. Requires the list tool to be enabled.
+         *
+         * @param params Lists opted-in local peers. The caller is omitted.
+         *
+         * @returns Eligible live peers reported by their owning runtimes.
+         */
+        list: (params: SessionManagementListRequest) => Promise<SessionManagementListResult>;
+        /**
+         * Injects peer text into an opted-in session. Wakes an idle agent and safely queues delivery to a busy agent. Acceptance does not imply an answer or completed task.
+         *
+         * @param params Sends peer text, never human approval, to another opted-in session.
+         *
+         * @returns Acceptance is not a completed turn or a reply.
+         */
+        message: (params: SessionManagementMessageRequest) => Promise<SessionManagementMessageResult>;
+        /**
+         * Asks the owning host to create and supervise a separate session, preserving permissions and model restrictions. Omitted model, reasoning effort, context tier and cwd inherit the caller's current values; explicit overrides use normal model validation and workspace trust. Records durable creation lineage before delivering the initial task as peer text. Returns the new session ID, not task completion. Requires the create tool and a host creation handler.
+         *
+         * @param params Requests a separate session. Omitted launch options inherit the caller's current configuration.
+         *
+         * @returns Identifies a session owned and supervised by the creating host.
+         */
+        create: (params: SessionManagementCreateRequest) => Promise<SessionManagementCreateResult>;
+        /**
+         * Closes a live opted-in session created by the caller or one of its descendants, preserving saved history and leaving descendants open. Requires the close capability to be enabled. Self, ancestors, siblings and unrelated sessions cannot be closed.
+         *
+         * @param params Closes one live opted-in descendant without deleting its saved history or closing its children.
+         *
+         * @returns Completion of the existing non-deleting close lifecycle.
+         */
+        close: (params: SessionManagementCloseRequest) => Promise<SessionManagementCloseResult>;
+    };
     /** @experimental */
     providers: {
         /**
@@ -39443,6 +39892,12 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          * @returns Canonical runtime state for the session's current autopilot objective.
          */
         getState: () => Promise<AutopilotObjectiveGetStateResult>;
+        /**
+         * Sets whether completing or pausing this session's objective preserves autopilot mode. This in-memory preference defaults to false and must be reapplied when attaching a client.
+         *
+         * @param params Client-resolved preference for retaining autopilot mode after objective completion or pause.
+         */
+        setStayInAutopilot: (params: AutopilotObjectiveSetStayInAutopilotRequest) => Promise<void>;
     };
     /** @experimental */
     completions: {
@@ -40182,6 +40637,12 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          * @returns The selectable model entries and selection ids synthesized for the synchronized BYOK models.
          */
         sync: (params: ProviderSyncRequest) => Promise<ProviderSyncResult>;
+        /**
+         * Returns credential-free provider configuration status for the selected model. This does not validate provider credentials or contact the provider.
+         *
+         * @returns Credential-free provider configuration status for the selected model.
+         */
+        getStatus: () => Promise<ProviderStatus>;
         /**
          * Withdraws named host-managed models from the session's BYOK registry, leaving every other entry untouched. The scoped counterpart to `provider.sync`: a snapshot can only describe entries the caller knows about, so using it to remove one model silently withdraws rows registered by another source, such as a plugin calling `provider.add` at runtime. Naming what to remove leaves unrelated entries alone. Selection ids that are not registered are ignored, so withdrawal is idempotent. A provider is removed only when one of the withdrawn models was the last entry referencing it; a provider that simply has no models, which is the normal state while its rows are supplied by catalog discovery, is left in place.
          *
@@ -40522,6 +40983,12 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          * @returns Current permission mode.
          */
         getMode: () => Promise<PermissionsGetModeResult>;
+        /**
+         * Returns the approval modes currently available under the session's feature and managed permission policy. This read does not change permissions; mutations must still check their authoritative result because policy may change.
+         *
+         * @returns Available permission modes, derived from current session policy.
+         */
+        getCapabilities: () => Promise<PermissionsCapabilities>;
         /**
          * Adds or removes session-scoped or location-scoped permission rules.
          *