Module: Copilot

Defined in:
lib/copilot/version.rb,
lib/copilot.rb,
lib/copilot/types.rb,
lib/copilot/client.rb,
lib/copilot/session.rb,
lib/copilot/define_tool.rb,
lib/copilot/json_rpc_client.rb,
lib/copilot/sdk_protocol_version.rb

Overview

Code generated by update-protocol-version. DO NOT EDIT.

Defined Under Namespace

Modules: ConnectionState, PermissionKind, SectionOverrideAction, SessionEventType, SessionFsProvider, SessionLifecycleEventType, SystemPromptSection, ToolResultType Classes: AssistantImageData, ClientOptions, CommandContext, CommandDefinition, ContentBlock, CopilotClient, CopilotSession, CustomAgentConfig, ElicitationContext, ElicitationResult, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, ImageOptions, InfiniteSessionConfig, JsonRpcClient, JsonRpcError, MCPLocalServerConfig, MCPRemoteServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelLimits, ModelPolicy, ModelSupports, ModelVisionLimits, PermissionRequest, PermissionRequestResult, PingResponse, ProviderConfig, ResumeSessionConfig, SectionOverride, SessionConfig, SessionEvent, SessionFsConfig, SessionFsFileInfo, SessionHooks, SessionLifecycleEvent, SessionLifecycleMetadata, SessionMetadata, StopError, SystemMessageAppendConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, Tool, ToolBinaryResult, ToolInvocation, ToolResult, UserInputRequest, UserInputResponse

Constant Summary collapse

RESPONSE_FORMATS =

Response format for message responses.

%w[text image json_object].freeze
VERSION = 
"2.0.0"
SDK_PROTOCOL_VERSION =

The SDK protocol version. This must match the version expected by the copilot-agent-runtime server.

2

Class Method Summary collapse

Class Method Details

.define_tool(name:, description: nil, parameters: nil) {|args, invocation| ... } ⇒ Tool

Helper for defining tools with a concise DSL.

Examples:

weather_tool = Copilot.define_tool(
  name: "get_weather",
  description: "Get weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" },
      unit:     { type: "string", enum: ["celsius", "fahrenheit"] }
    },
    required: ["location"]
  }
) do |args, invocation|
  location = args["location"] || args[:location]
  "Weather in #{location}: 22 degrees, sunny"
end

Parameters:

  • name (String) —

    tool name

  • description (String) (defaults to: nil) —

    human-readable description

  • parameters (Hash, nil) (defaults to: nil) —

    JSON Schema for the tool parameters

Yields:

  • (args, invocation) —

    called when the tool is invoked

Yield Parameters:

  • args (Hash) —

    parsed arguments from the LLM

  • invocation (ToolInvocation) —

    context about the invocation

Yield Returns:

Returns:

Raises:

  • (ArgumentError) 


33
34
35
36
37
38
39
40
41
42
 
# File 'lib/copilot/define_tool.rb', line 33

def self.define_tool(name:, description: nil, parameters: nil, &handler)
  raise ArgumentError, "Block required for tool handler" unless handler

  Tool.new(
    name: name,
    description: description,
    parameters: parameters,
    handler: handler
  )
end

.normalize_tool_result(result) ⇒ Hash

Normalize a tool handler’s return value into a wire-format Hash.

  • nil is treated as a failure (no result).

  • String is wrapped as a successful text result.

  • ToolResult is converted via to_h.

  • Hash with textResultForLlm key passes through (duck-typed ToolResultObject).

  • Any other value is JSON-serialized as a successful text result.

Parameters:

  • result (Object) —

    the raw handler return value

Returns:

  • (Hash) —

    normalized wire-format tool result



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/copilot/define_tool.rb', line 54

def self.normalize_tool_result(result)
  if result.nil?
    return {
      textResultForLlm: "Tool returned no result",
      resultType: ToolResultType::FAILURE,
      error: "tool returned no result",
      toolTelemetry: {},
    }
  end

  # ToolResult struct
  if result.is_a?(ToolResult)
    return result.to_h
  end

  # Hash that looks like a ToolResultObject (duck-type check)
  if result.is_a?(Hash) && (result.key?(:textResultForLlm) || result.key?("textResultForLlm"))
    return result
  end

  # String passes through as success
  text = result.is_a?(String) ? result : JSON.generate(result)
  {
    textResultForLlm: text,
    resultType: ToolResultType::SUCCESS,
    toolTelemetry: {},
  }
end

.sdk_protocol_version ⇒ Integer

Returns the SDK protocol version number.

Returns:

  • (Integer) —

    the SDK protocol version number



13
14
15
 
# File 'lib/copilot/sdk_protocol_version.rb', line 13

def self.sdk_protocol_version
  SDK_PROTOCOL_VERSION
end