HalChat: GitHub Copilot Chat Session

In hal: Agentic Coding Assistants

GitHub Copilot Chat Session

Description

High-level chat interface to GitHub Copilot models. Manages conversation history, tool registration, and streaming. API surface mirrors ellmer::Chat for familiarity.

Uses HalClient for JSON-RPC transport to the Copilot SDK CLI, which handles model-specific format translation internally – no proxy translation bugs.

The ACP server maintains conversation history server-side. Turns are also tracked locally so you can inspect them with ⁠$get_turns()⁠.

Value

An R6 object of class HalChat. Methods return values as documented per method; construct with HalChat$new().

Methods

Public methods

• HalChat$new()

• HalChat$chat()

• HalChat$register_tool()

• HalChat$register_tools()

• HalChat$get_turns()

• HalChat$last_response()

• HalChat$last_turn()

• HalChat$last_tool_calls()

• HalChat$switch_model()

• HalChat$set_mode()

• HalChat$cancel()

• HalChat$get_model()

• HalChat$get_client()

• HalChat$clone()

---

HalChat$new()

Create a new Copilot chat session.

Usage

HalChat$new(
  model = NULL,
  system_prompt = NULL,
  client = NULL,
  echo = NULL,
  on_text = NULL,
  on_tool_call = NULL,
  on_thought = NULL,
  mode = NULL,
  permission_policy = "auto-allow",
  quiet = FALSE
)

Arguments

model

Model identifier (e.g., "claude-sonnet-5", "gpt-5.2"). If NULL, uses the server default.

system_prompt

System prompt string.

client

A HalClient instance, or NULL to create one.

echo

Echo mode: "none", "output", or "all".

on_text

Callback for streaming text chunks: ⁠function(chunk)⁠.

on_tool_call

Callback for tool call events: ⁠function(tool_call)⁠.

on_thought

Callback for thought chunks: ⁠function(chunk)⁠.

mode

Session mode: "agent" (default), "plan", or "autopilot". Applied after the session is created on the first prompt.

permission_policy

Permission policy for the agent: "auto-allow", "auto-deny", or a custom function. Ignored if client is provided.

quiet

Logical; suppress informational messages (default: FALSE).

---

HalChat$chat()

Send a message and get a response.

Usage

HalChat$chat(..., timeout = NULL)

Arguments

...

Character strings, concatenated as the user message.

timeout

Timeout in seconds for the response.

Returns

Assistant's text response (invisibly if echo != "none").

---

HalChat$register_tool()

Register a tool for the model to call.

Usage

HalChat$register_tool(tool)

Arguments

tool

A tool definition. Can be an ellmer::ToolDef or a list with name, description, parameters, and fun fields.

---

HalChat$register_tools()

Register multiple tools.

Usage

HalChat$register_tools(tools)

Arguments

tools

A list of tool definitions.

---

HalChat$get_turns()

Get conversation turns.

Usage

HalChat$get_turns(include_system_prompt = FALSE)

Arguments

include_system_prompt

Include the system prompt turn.

Returns

List of turn objects.

---

HalChat$last_response()

Get the full response from the last prompt.

Usage

HalChat$last_response()

Returns

A hal_response object, or NULL if no responses yet.

---

HalChat$last_turn()

Get the last assistant turn.

Usage

HalChat$last_turn()

Returns

A hal_turn object, or NULL if no turns yet.

---

HalChat$last_tool_calls()

Get tool calls from the last assistant turn.

Usage

HalChat$last_tool_calls()

Returns

List of hal_tool_call objects, or NULL if none.

---

HalChat$switch_model()

Switch models mid-session without losing context.

Usage

HalChat$switch_model(model)

Arguments

model

Model identifier (e.g., "gpt-4.1", "claude-haiku-4.5").

Returns

Invisibly returns self.

---

HalChat$set_mode()

Set the session mode.

Usage

HalChat$set_mode(mode = c("agent", "plan", "autopilot"))

Arguments

mode

"agent" (default), "plan", or "autopilot".

Returns

Invisibly returns self.

---

HalChat$cancel()

Cancel the current in-flight prompt.

Stops the streaming loop and returns a partial response with stop_reason = "interrupted". For interactive use, Ctrl+C (ESC in RStudio) during ⁠$chat()⁠ achieves the same effect automatically.

Useful from Shiny observers, callbacks, or a second R session.

Usage

HalChat$cancel()

Returns

Invisibly returns self.

---

HalChat$get_model()

Get the model identifier.

Usage

HalChat$get_model()

Returns

Character string.

---

HalChat$get_client()

Get the underlying client.

Usage

HalChat$get_client()

Returns

A HalClient instance.

---

HalChat$clone()

The objects of this class are cloneable with this method.

Usage

HalChat$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

See Also

HalClient for the low-level transport layer, hal_models() for available models.

Examples

## Not run: 
# Preferred: use hal_chat()
chat <- hal_chat()
chat$chat("Explain the pipe operator in R")

# Or use R6 constructor directly
chat <- HalChat$new(model = "gpt-5.2")
chat$chat("Hello!")

## End(Not run)

hal documentation built on Oct. 6, 2026, 5:07 p.m.