Phase 7: Complete API Surface Reference

class MessageOptions(TypedDict):
    prompt: str
    attachments: NotRequired[list[Attachment]]
    mode: NotRequired[Literal["enqueue", "immediate"]]

type MessageOptions struct {
    Prompt      string
    Attachments []Attachment
    Mode        string  // "enqueue" or "immediate"
}

public class MessageOptions {
    public string Prompt { get; init; }
    public List<Attachment>? Attachments { get; init; }
    public string? Mode { get; init; }
}

type ProviderConfig struct {
    Type        string                 `json:"type,omitempty"`
    WireApi     string                 `json:"wireApi,omitempty"`
    BaseURL     string                 `json:"baseUrl"`
    APIKey      string                 `json:"apiKey,omitempty"`
    BearerToken string                 `json:"bearerToken,omitempty"`
    Azure       *AzureProviderOptions  `json:"azure,omitempty"`
}

// Single struct with typed data
type SessionEvent struct {
    Data      Data             `json:"data"`
    Ephemeral *bool            `json:"ephemeral,omitempty"`
    ID        string           `json:"id"`
    ParentID  *string          `json:"parentId"`
    Timestamp time.Time        `json:"timestamp"`
    Type      SessionEventType `json:"type"`
}

// Class hierarchy
public abstract class SessionEvent { ... }
public class AssistantMessageEvent : SessionEvent { ... }
public class SessionIdleEvent : SessionEvent { ... }
public class SessionErrorEvent : SessionEvent { ... }
public class ExternalToolRequestedEvent : SessionEvent { ... }
public class PermissionRequestedEvent : SessionEvent { ... }

from pydantic import BaseModel, Field
from copilot import define_tool

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")
    unit: str = Field(description="Temperature unit")

# Decorator approach
@define_tool(description="Get weather for a city")
def get_weather(params: GetWeatherParams) -> str:
    return f"Weather in {params.city}: 22 degrees {params.unit}"

# Tool dataclass
@dataclass
class Tool:
    name: str
    description: str
    handler: ToolHandler
    parameters: dict[str, Any] | None = None
    overrides_built_in_tool: bool = False

type GetWeatherParams struct {
    City string `json:"city" jsonschema:"city name"`
    Unit string `json:"unit" jsonschema:"temperature unit"`
}

tool := copilot.DefineTool("get_weather", "Get weather for a city",
    func(params GetWeatherParams, inv copilot.ToolInvocation) (any, error) {
        return fmt.Sprintf("Weather in %s: 22 degrees %s",
            params.City, params.Unit), nil
    })

// Tool struct
type Tool struct {
    Name                 string         `json:"name"`
    Description          string         `json:"description,omitempty"`
    Parameters           map[string]any `json:"parameters,omitempty"`
    OverridesBuiltInTool bool           `json:"overridesBuiltInTool,omitempty"`
    Handler              ToolHandler    `json:"-"`
}

using Microsoft.Extensions.AI;

// Define tool from a method
[Description("Get weather for a location")]
static string GetWeather(string location) => $"Weather in {location}: 72F";

var session = await client.CreateSessionAsync(new()
{
    OnPermissionRequest = PermissionHandler.ApproveAll,
    Tools = [AIFunctionFactory.Create(GetWeather)]
});

// ToolInvocation class
public class ToolInvocation {
    public string SessionId { get; set; }
    public string ToolCallId { get; set; }
    public string ToolName { get; set; }
    public object? Arguments { get; set; }
}

type ToolResult struct {
    TextResultForLLM    string             `json:"textResultForLlm"`
    BinaryResultsForLLM []ToolBinaryResult `json:"binaryResultsForLlm,omitempty"`
    ResultType          string             `json:"resultType"`
    Error               string             `json:"error,omitempty"`
    SessionLog          string             `json:"sessionLog,omitempty"`
    ToolTelemetry       map[string]any     `json:"toolTelemetry,omitempty"`
}

class SessionHooks(TypedDict, total=False):
    on_pre_tool_use: PreToolUseHandler
    on_post_tool_use: PostToolUseHandler
    on_user_prompt_submitted: UserPromptSubmittedHandler
    on_session_start: SessionStartHandler
    on_session_end: SessionEndHandler
    on_error_occurred: ErrorOccurredHandler

type SessionHooks struct {
    OnPreToolUse          PreToolUseHandler
    OnPostToolUse         PostToolUseHandler
    OnUserPromptSubmitted UserPromptSubmittedHandler
    OnSessionStart        SessionStartHandler
    OnSessionEnd          SessionEndHandler
    OnErrorOccurred       ErrorOccurredHandler
}

public class SessionHooks {
    public PreToolUseHandler? OnPreToolUse { get; set; }
    public PostToolUseHandler? OnPostToolUse { get; set; }
    public UserPromptSubmittedHandler? OnUserPromptSubmitted { get; set; }
    public SessionStartHandler? OnSessionStart { get; set; }
    public SessionEndHandler? OnSessionEnd { get; set; }
    public ErrorOccurredHandler? OnErrorOccurred { get; set; }
}

from copilot import CopilotClient, PermissionHandler

async with CopilotClient() as client:
    session = await client.create_session({
        "on_permission_request": PermissionHandler.approve_all,
        "model": "gpt-4",
    })

client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, err := client.CreateSession(ctx, &copilot.SessionConfig{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    Model:               "gpt-4",
})

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new()
{
    OnPermissionRequest = PermissionHandler.ApproveAll,
    Model = "gpt-4",
});

response = await session.send_and_wait({"prompt": "What is 2+2?"})
if response:
    print(response.data.content)

response, err := session.SendAndWait(ctx, copilot.MessageOptions{
    Prompt: "What is 2+2?",
})
if response != nil {
    fmt.Println(*response.Data.Content)
}

var response = await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "What is 2+2?"
});
Console.WriteLine(response?.Data?.Content);

from pydantic import BaseModel
from copilot import define_tool

class WeatherParams(BaseModel):
    city: str

@define_tool(description="Get weather for a location")
def get_weather(params: WeatherParams) -> str:
    return f"Weather in {params.city}: 72F"

type WeatherParams struct {
    City string `json:"city"`
}

tool := copilot.DefineTool("get_weather", "Get weather for a location",
    func(params WeatherParams, inv copilot.ToolInvocation) (any, error) {
        return fmt.Sprintf("Weather in %s: 72F", params.City), nil
    })

[Description("Get weather for a location")]
static string GetWeather(string city) => $"Weather in {city}: 72F";

// Pass as: Tools = [AIFunctionFactory.Create(GetWeather)]

def handler(event):
    if event.type == "assistant.message":
        print(f"Assistant: {event.data.content}")

unsubscribe = session.on(handler)
# Later: unsubscribe()

unsubscribe := session.On(func(event copilot.SessionEvent) {
    if event.Type == copilot.AssistantMessage {
        fmt.Println("Assistant:", *event.Data.Content)
    }
})
// Later: unsubscribe()

using var subscription = session.On(evt =>
{
    if (evt is AssistantMessageEvent msg)
    {
        Console.WriteLine($"Assistant: {msg.Data?.Content}");
    }
});
// Auto-unsubscribed when disposed

# Manual
await session.disconnect()
await client.stop()

# Context manager
async with CopilotClient() as client:
    session = await client.create_session({ ... })

// Always manual with defer
defer client.Stop()
defer session.Disconnect()

// Manual
await session.DisposeAsync();
await client.DisposeAsync();

// Auto-dispose
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new() { ... });