[];
}
-/** Structured error returned from canvas handlers. */
+/**
+ * Structured error returned from canvas handlers.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
export class CanvasError extends Error {
constructor(
public readonly code: string,
@@ -82,6 +100,9 @@ export class CanvasError extends Error {
/**
* Options accepted by {@link createCanvas}. Combines the declarative
* {@link CanvasDeclaration} fields with the in-process handler closures.
+ *
+ * @experimental This interface is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
*/
export interface CanvasOptions {
/** @see CanvasDeclaration.id */
@@ -119,6 +140,9 @@ export interface CanvasOptions {
* ergonomics) where other SDKs (Rust, Python, Go, .NET) expose a single
* `CanvasHandler` per session that switches on `canvasId`. Both shapes target
* the same JSON-RPC wire protocol; the divergence is API ergonomics only.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
*/
export class Canvas {
readonly declaration: CanvasDeclaration;
@@ -156,6 +180,9 @@ export class Canvas {
* `DefineTool`'s co-location ergonomics) where other SDKs (Rust, Python, Go,
* .NET) expose a single `CanvasHandler` per session that switches on
* `canvasId`. Both shapes target the same JSON-RPC wire protocol.
+ *
+ * @experimental This function is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
*/
export function createCanvas(options: CanvasOptions): Canvas {
return new Canvas(options);
diff --git a/nodejs/src/index.ts b/nodejs/src/index.ts
index c39621c0b..c0390a5f2 100644
--- a/nodejs/src/index.ts
+++ b/nodejs/src/index.ts
@@ -18,6 +18,7 @@ export {
type CanvasAction,
type CanvasDeclaration,
type CanvasHostContext,
+ type CanvasHostContextCapabilities,
type CanvasJsonSchema,
type CanvasOptions,
} from "./canvas.js";
diff --git a/python/copilot/canvas.py b/python/copilot/canvas.py
index 772c15b39..ddbc8539a 100644
--- a/python/copilot/canvas.py
+++ b/python/copilot/canvas.py
@@ -6,6 +6,11 @@
user-supplied :class:`CanvasHandler`; multiplexing across multiple declared
canvases is the implementor's responsibility (for example by switching on
``ctx.canvas_id``).
+
+.. note::
+
+ **Experimental.** Canvas types are part of an experimental wire-protocol
+ surface and may change or be removed in future SDK or CLI releases.
"""
from __future__ import annotations
@@ -44,6 +49,11 @@ class ExtensionInfo:
"""Stable extension identity for session participants that provide canvases.
Serializes to ``{"source": ..., "name": ...}`` on the wire.
+
+ .. note::
+
+ **Experimental.** This type is part of an experimental wire-protocol
+ surface and may change or be removed in future SDK or CLI releases.
"""
source: str
@@ -58,7 +68,13 @@ def to_dict(self) -> dict[str, Any]:
@dataclass
class CanvasDeclaration:
- """Declarative metadata for a single canvas, sent on create/resume."""
+ """Declarative metadata for a single canvas, sent on create/resume.
+
+ .. note::
+
+ **Experimental.** This type is part of an experimental wire-protocol
+ surface and may change or be removed in future SDK or CLI releases.
+ """
id: str
"""Canvas identifier, unique within the declaring connection."""
@@ -89,7 +105,13 @@ def to_dict(self) -> dict[str, Any]:
class CanvasError(Exception):
- """Structured error returned from canvas handlers."""
+ """Structured error returned from canvas handlers.
+
+ .. note::
+
+ **Experimental.** This type is part of an experimental wire-protocol
+ surface and may change or be removed in future SDK or CLI releases.
+ """
def __init__(self, code: str, message: str) -> None:
self.code = code
@@ -118,7 +140,13 @@ def handler_unset(cls) -> CanvasError:
class CanvasHandler(ABC):
- """Provider-side canvas lifecycle handler."""
+ """Provider-side canvas lifecycle handler.
+
+ .. note::
+
+ **Experimental.** This type is part of an experimental wire-protocol
+ surface and may change or be removed in future SDK or CLI releases.
+ """
@abstractmethod
async def on_open(self, ctx: CanvasProviderOpenRequest) -> CanvasProviderOpenResult:
diff --git a/rust/src/canvas.rs b/rust/src/canvas.rs
index 15cbb031d..c87395874 100644
--- a/rust/src/canvas.rs
+++ b/rust/src/canvas.rs
@@ -1,4 +1,11 @@
//! Canvas declarations, provider callbacks, and host-side canvas RPC types.
+//!
+//!
+//!
+//! **Experimental.** Canvas types are part of an experimental wire-protocol surface
+//! and may change or be removed in future SDK or CLI releases.
+//!
+//!
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
@@ -8,11 +15,25 @@ use thiserror::Error;
use crate::generated::api_types::CanvasAction;
/// JSON Schema object used for canvas inputs and canvas-scoped tools.
+///
+///
+///
+/// **Experimental.** This type is part of an experimental wire-protocol surface
+/// and may change or be removed in future SDK or CLI releases.
+///
+///
pub type CanvasJsonSchema = serde_json::Map;
/// Declarative metadata for a single canvas, sent over the wire on
/// `session.create` / `session.resume`.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+///
+///
+///
+/// **Experimental.** This type is part of an experimental wire-protocol surface
+/// and may change or be removed in future SDK or CLI releases.
+///
+///
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CanvasDeclaration {
@@ -54,6 +75,13 @@ impl CanvasDeclaration {
}
/// Structured error returned from canvas handlers.
+///
+///
+///
+/// **Experimental.** This type is part of an experimental wire-protocol surface
+/// and may change or be removed in future SDK or CLI releases.
+///
+///
#[derive(Debug, Clone, Error, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[error("{code}: {message}")]
@@ -83,10 +111,24 @@ impl CanvasError {
}
/// Result alias for canvas handler methods.
+///
+///
+///
+/// **Experimental.** This type is part of an experimental wire-protocol surface
+/// and may change or be removed in future SDK or CLI releases.
+///
+///
pub type CanvasResult = Result;
/// Provider-side canvas lifecycle handler.
///
+///
+///
+/// **Experimental.** This trait is part of an experimental wire-protocol surface
+/// and may change or be removed in future SDK or CLI releases.
+///
+///
+///
/// A session installs a single [`CanvasHandler`] (via
/// [`SessionConfig::with_canvas_handler`](crate::types::SessionConfig::with_canvas_handler)).
/// The handler receives every inbound `canvas.open` / `canvas.close` /