Package 'hal'

Description

The main entry point for conversational interaction with Copilot models. Maintains a persistent session across calls. The SDK agent has built-in tools for file operations, code search, and shell commands.

Usage

hal(..., model = NULL, use_env = NULL, reset = FALSE, inspect = FALSE)

Arguments

Value

The assistant's text response (invisibly when displayed).

Errors in scripts

In an interactive session a transport failure prints an alert and returns invisible(NULL). In non-interactive contexts (scripts, R Markdown) it aborts with a classed condition instead, so programmatic callers can handle hal failures specifically: tryCatch(hal("..."), hal_transport_error = function(e) ...). All hal conditions inherit from hal_error / hal_warning; hal_do() signals hal_do_error / hal_do_warning, and hal_ask() signals hal_ask_warning.

Examples

## Not run: 
# Simple conversation
hal("What is R?")
hal("Can you explain more about data frames?")

# Environment access (auto-detected when objects exist)
df <- mtcars
hal("What's the mean mpg?")   # auto-detects df, injects env snapshot

# Reset and start fresh
hal("Hello", reset = TRUE)

# Inspect session
hal(inspect = TRUE)

## End(Not run)

Description

Pipe mode: a pipe-terminal verb that sends a prompt to Copilot augmented with the piped data context. The piped object is described via str() and attached to the prompt. Returns .data invisibly (pipe passthrough).

Usage

hal_ask(.data, ...)

Arguments

Details

Standalone mode: called directly with a string prompt to ask a question without data context. Returns the response text invisibly.

Spawns a disposable session – does NOT pollute the main hal() conversation.

Value

Pipe mode: invisibly returns .data (pipe passthrough). Standalone: invisibly returns the response text.

Examples

## Not run: 
# Pipe mode (data-aware analysis)
mtcars |> hal_ask("what are the key patterns?")
lm(mpg ~ wt, data = mtcars) |> hal_ask("interpret these coefficients")

# Standalone mode (general question)
hal_ask("what does the pipe operator do in R?")
hal_ask("explain", "the difference between <- and =")

## End(Not run)

Description

Dispatches by backend:

• vscode: bridge port file exists and ⁠/version⁠ responds.

• copilot: Copilot CLI binary found and --version succeeds.

• claude: Claude CLI binary found and --version succeeds.

Usage

hal_available(backend = NULL)

Arguments

Details

Honors the hal.backend option / explicit argument so callers can probe a specific backend without switching the session default.

Value

TRUE if the backend's transport is reachable, FALSE otherwise.

See Also

HalChat, hal_models(), hal_bridge_status() for richer vscode-backend diagnostics.

Examples

hal_available()
## Not run: 
hal_available(backend = "vscode")
hal_available(backend = "claude")

## End(Not run)

Description

Reads the bridge port file, pings the ⁠/version⁠ endpoint, and warns on version drift between the running bridge and the version this hal release was pinned against.

Usage

hal_bridge_status()

Value

Invisibly returns TRUE if the bridge is reachable, FALSE otherwise. Always prints a status line as a side effect.

See Also

hal_install_bridge().

Examples

## Not run: 
hal_bridge_status()

## End(Not run)

Description

Creates a new HalChat instance for conversing with GitHub Copilot models. This is the recommended entry point – equivalent to HalChat$new() but follows tidyverse naming conventions.

Usage

hal_chat(
  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

Value

A HalChat object.

See Also

hal_models(), hal_client(), hal_available()

Examples

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

# Specific model
chat <- hal_chat(model = "gpt-5.2")
chat$chat("Hello!")

# With system prompt
chat <- hal_chat(
  model = "claude-haiku-4.5",
  system_prompt = "Reply concisely in one sentence."
)
chat$chat("What is R?")

# Plan mode
chat <- hal_chat(mode = "plan")
chat$chat("Create an analysis plan for this dataset")

# With streaming callbacks
chat <- hal_chat(
  on_text = function(chunk) cat(chunk),
  on_tool_call = function(tc) message("Tool: ", tc$title)
)

# Read-only mode (deny file writes and shell commands)
chat <- hal_chat(permission_policy = "auto-deny")
chat$chat("What files are in R/?")

## End(Not run)

Description

Creates a new HalClient instance for low-level ACP communication. Most users should use hal_chat() instead.

Usage

hal_client(
  model = NULL,
  cli_path = NULL,
  permission_policy = "auto-allow",
  on_text = NULL,
  on_tool_call = NULL,
  on_thought = NULL,
  quiet = FALSE
)

Arguments

Value

A HalClient object.

See Also

hal_chat(), hal_available()

Examples

## Not run: 
client <- hal_client()
client$start()
client$handshake()
session <- client$new_session()
client$stop()

## End(Not run)

Description

Returns a named list of all active settings.

Usage

hal_config()

Value

A named list of configuration values.

Examples

cfg <- hal_config()
cfg$backend
cfg$eval_timeout

Description

Set display, governance, and session defaults. Settings persist for the duration of the R session via options().

Usage

hal_configure(
  use_colors = NULL,
  stream = NULL,
  stream_speed = NULL,
  default_model = NULL,
  system_prompt = NULL,
  eval_denylist = NULL,
  credential_action = NULL,
  eval_timeout = NULL,
  prompt_timeout = NULL,
  prompt_timeout_cold = NULL,
  edit_in_place = NULL,
  do_retries = NULL,
  do_on_fail = NULL,
  verify = NULL,
  plot_vision = NULL,
  permission_policy = NULL,
  session_quiet = NULL,
  init_quiet = NULL,
  show_thoughts = NULL,
  backend = NULL,
  quiet = FALSE
)

Arguments

Value

Invisibly returns a list of changes made.

Examples

hal_configure(stream = FALSE, do_retries = 1, quiet = TRUE)
hal_config()$stream
# unset again to restore the defaults
options(hal.stream = NULL, hal.do_retries = NULL)

Description

Pipe mode: a mid-pipe transformation verb that generates R code, executes it, and returns the result.

Usage

hal_do(.data, ..., .model = NULL, .retries = NULL, .verify = NULL)

Arguments

Details

Standalone mode: called directly with a string prompt to generate and execute R code in the caller's environment.

Spawns a disposable session – does NOT pollute the main conversation. Governance controls (denylist, credential scanner, timeout) are enforced.

Value

Pipe mode: transformed data. Standalone: result of generated code (invisible).

Failure behavior

In an interactive session, a failure (after retries) warns and returns .data unchanged (pipe) or invisible(NULL) (standalone) – forgiving for console exploration. In non-interactive contexts (scripts, R Markdown, targets), it aborts instead: a pipeline silently continuing with untransformed data is worse than an error. Override either way with options(hal.do_on_fail = "warn") or "abort". All failures signal classed conditions (hal_do_error / hal_do_warning), so you can tryCatch(..., hal_do_error = function(e) ...).

Examples

## Not run: 
# Pipe mode
mtcars |> hal_do("keep only cars with mpg > 25")
iris |> hal_do("add a column for petal area") |> head()

# Standalone mode
hal_do("write a function called greet that takes a name")
greet("world")

# Disable retries
mtcars |> hal_do("normalize mpg", .retries = 0)

## End(Not run)

Description

Reads an .xlsx, treats columns without formulas as data, and translates each formula column into a tidyverse expression via the active hal backend. Returns a runnable R script – a line that reads the input columns from the workbook plus a mutate() pipeline that recreates the formula columns – so you can replace the spreadsheet (and the hal_excel() call) with the code.

Usage

hal_excel(path, sheet = 1, model = NULL, tolerance = NULL, retries = NULL)

## S3 method for class 'hal_excel_code'
print(x, ...)

Arguments

Details

Works like hal_do() under the hood (disposable worker, code extraction, denylist, timed eval, retry loop), with one addition: each translation is run and checked against the values Excel cached, so only columns that match Excel row-for-row go into the live pipeline; the rest are emitted as commented stubs to review.

Each formula column is assumed to hold one formula filled down the column (a vectorised expression, e.g. ⁠=A2*B2⁠), so its first formula is translated once. A workbook with no cached values is still translated but reported unverifiable.

Value

A hal_excel_code object (a character string of R code) that prints as the generated script. The per-column report is attached as attr(result, "hal_excel"). Save it with writeLines(result, "out.R").

Examples

## Not run: 
hal_excel("model.xlsx")                # prints the read + mutate script
code <- hal_excel("model.xlsx")
writeLines(code, "model.R")         # or paste it in place of the call
attr(code, "hal_excel")               # per-column verification report

## End(Not run)

Description

Display or return the conversation turns from the active session.

Usage

hal_history(
  role = NULL,
  pattern = NULL,
  format = c("console", "data.frame", "text"),
  n = NULL
)

Arguments

Value

Depends on format: invisible NULL for console, a data.frame, or a character vector.

Examples

# with no active session this returns an empty data frame
hal_history(format = "data.frame")
## Not run: 
hal_history()                      # print all turns
hal_history(role = "user", n = 5)  # last five user prompts
hal_history(pattern = "ggplot")    # turns mentioning ggplot

## End(Not run)

Description

Installs the hal-bridge VSIX shipped with this hal release into Positron. No download, no GitHub auth, no SHA verification: the bytes installed are the bytes that shipped in ⁠inst/extdata/⁠. Reload Positron after installing to activate the bridge.

Usage

hal_install_bridge(local_path = NULL, force = FALSE)

Arguments

Details

The vscode backend (hal_configure(backend = "vscode")) requires this extension. Other backends (copilot, claude) do not.

Value

Invisibly returns the installed VSIX path.

See Also

hal_bridge_status() to check whether it's actually running.

Examples

## Not run: 
hal_install_bridge()
hal_install_bridge(local_path = "~/Downloads/hal-bridge-dev.vsix")

## End(Not run)

Description

Returns the full per-model record, including the raw ⁠_meta⁠ payload from the ACP server. Useful for debugging or accessing fields that hal_models() doesn't surface as columns.

Usage

hal_model_info(id = NULL, client = NULL)

Arguments

Value

A list with id, name, description, provider, family, usage, multiplier, is_default, context_window, release_date, and meta (raw ⁠_meta⁠ list from the server, or NULL for Claude).

Examples

## Not run: 
ids <- hal_model_info()   # print available ids
hal_model_info(ids[[1]])  # inspect the first one

## End(Not run)

Description

Returns a data frame describing the models exposed by the active backend.

Usage

hal_models(client = NULL)

Arguments

Details

• Copilot: queries the ACP server (session/new) to fetch live model metadata.

• Claude: returns the alias selectors (opus/sonnet/haiku), which Anthropic resolves to the latest model of each tier – the Claude CLI exposes no live model list. Pass a concrete id (e.g. "claude-opus-5") to ⁠model=⁠ if you need to pin a version.

• vscode: queries the hal-bridge ⁠/models⁠ endpoint, which returns whatever models vscode.lm exposes to your Copilot session.

Value

A data frame with columns:

• id — model identifier (matches --model flag)

• name — display name

• description — vendor-supplied prose (may be NA)

• provider — "openai", "anthropic", "google", or "unknown"

• family — coarse tier: "light", "standard", "heavy"

• usage — billing tier label (e.g. "1x", "0.33x", "0x")

• multiplier — numeric form of usage

• is_default — TRUE if currently selected as session default

• context_window — token limit when known (NA otherwise)

• release_date — ISO date when known (NA otherwise)

See Also

hal_model_info() for full per-model detail (incl. raw ⁠_meta⁠).

Examples

## Not run: 
hal_models()
subset(hal_models(), provider == "anthropic")

## End(Not run)

Description

Plan mode (and occasionally Agent mode) asks the model to commit to a structured plan, written to ⁠~/.copilot/session-state/{sessionId}/plan.md⁠. hal_plan() returns the path so you can view or edit it directly.

Usage

hal_plan()

Value

Character path to plan.md, or NULL invisibly if no plan is available.

Examples

## Not run: 
hal_reset(mode = "plan")
hal("Investigate the Q4 revenue drop in `sales`")
hal_plan()                       # path to plan.md
file.edit(hal_plan())            # open in editor
readLines(hal_plan())            # read programmatically

## End(Not run)

Description

Returns the most recent rate_limit_event payload observed on the Claude backend during this session. Only populated after at least one hal(), hal_ask(), or hal_do() call – the event is embedded in the prompt response stream.

Usage

hal_quota()

Value

A hal_quota object (list) with fields type, status, resets_at (POSIXct), overage_status, overage_disabled_reason, backend. Returns NULL invisibly if no rate-limit info has been observed, or if the active backend is Copilot.

Examples

## Not run: 
hal("hello")
hal_quota()

## End(Not run)

Description

Discovers exported functions from a package and registers them as LLM-callable tools.

Usage

hal_register_package_tools(pkg, fns = NULL, exclude = NULL, prefix = NULL)

Arguments

Value

Invisibly returns a list of registered tool definitions.

Examples

## Not run: 
# expose a few dplyr verbs to the model
hal_register_package_tools("dplyr",
  fns = c("filter", "select", "arrange"), prefix = "dplyr_"
)

## End(Not run)

Description

Shorthand that builds a tool definition and registers it on the active session's chat object.

Usage

hal_register_tool(fn, name = NULL, description = NULL, types = NULL)

Arguments

Value

Invisibly returns the tool definition.

Examples

## Not run: 
get_time <- function(tz = "UTC") format(Sys.time(), tz = tz)
hal_register_tool(get_time,
  description = "Current time in a given timezone"
)
hal("what time is it in Tokyo?")

## End(Not run)

Description

Registers a list of tool specifications (as returned by e.g. winston::timelog_tool_specs()) on the active session.

Usage

hal_register_tool_specs(specs)

Arguments

Details

Each spec must be a list with at minimum name, description, and handler (a function). Optional: parameters (JSON Schema).

Value

Invisibly returns the number of tools registered.

Examples

## Not run: 
specs <- list(
  list(
    name = "row_count",
    description = "Count the rows of a data frame in the global environment",
    handler = function(name) nrow(get(name, envir = globalenv()))
  )
)
hal_register_tool_specs(specs)

## End(Not run)

Description

Registers a list of tools on the active hal() session so the model can call them. Each element may be an ellmer::ToolDef (e.g. from daisy::daisy_tools()) or a plain hal tool list with name / description / fun / parameters. Unlike hal_register_tool(), which builds a tool from a bare function's formals, this passes each element through the chat's tool normalizer, so pre-built ToolDefs keep their declared argument schema.

Usage

hal_register_tools(tools)

Arguments

Value

Invisibly, the number of tools registered.

See Also

hal_register_tool(), hal_register_tool_specs()

Examples

## Not run: 
tools <- list(
  hal_tool(function(x, y) x + y, "add",
    description = "Add two numbers",
    types = list(x = "number", y = "number")
  ),
  hal_tool(function(path) readLines(path), "read_file",
    description = "Read a text file"
  )
)
hal_register_tools(tools)

## End(Not run)

Description

Destroys the current session and starts fresh.

Usage

hal_reset(mode = NULL)

Arguments

Value

Invisibly returns NULL, called for its side effect.

Examples

## Not run: 
hal_reset()               # fresh session on the same backend
hal_reset(mode = "plan")  # restart in plan mode (copilot backend)

## End(Not run)

Description

An S3 class representing the full response from a single prompt. Returned internally by HalClient's prompt() method and used by HalChat.

Usage

## S3 method for class 'hal_response'
print(x, ...)

Arguments

Value

The print() method returns x invisibly. hal_response objects are created internally by the transport clients.

Fields

text

Character: the full response text.

stop_reason

Character: why the model stopped (e.g., "end_turn", "interrupted").

tool_calls

List of hal_tool_call objects.

thoughts

Character vector of agent thought text.

events

List of raw session/update events.

See Also

hal_turn, hal_tool_call

Description

Interactive helper that picks the right backend for the host and walks through prerequisites. Two paths:

Usage

hal_setup(force = FALSE, quiet = FALSE, backend = NULL)

Arguments

Details

• Positron (recommended): installs the hal-bridge extension from the VSIX bundled with hal, so hal talks to vscode.lm directly. No Node.js, no Copilot CLI, no GitHub CLI, no download – the only requirement is that you are signed in to GitHub Copilot inside Positron itself (the account menu in the lower left).

• Other hosts (RStudio, VS Code, command-line R): installs the GitHub Copilot CLI (⁠gh copilot⁠ extension preferred, npm ⁠@github/copilot⁠ fallback).

• Claude Code: verifies the claude CLI and points at the download and one-time sign-in. hal does not install this one for you: Claude Code's sign-in is an interactive browser flow, and installing it via npm yields a shim whose output is unreliable when driven from R.

Detection is via POSITRON_VERSION. Pass backend = "copilot" to force the Copilot CLI path inside Positron, or backend = "claude" to check the Claude Code CLI instead.

Value

Invisibly TRUE if the backend transport is available after setup, FALSE otherwise.

See Also

hal_available(), hal_install_bridge(), hal_bridge_status(), hal_models()

Examples

## Not run: 
hal_setup()                          # auto: vscode in Positron, copilot elsewhere
hal_setup(backend = "copilot")       # force the Copilot CLI path
hal_setup(backend = "claude")        # check the Claude Code CLI

## End(Not run)

Description

Prints a traffic-light report covering everything between you and a working hal() call: which backend is selected (and why), whether its transport is reachable, what the active session looks like, and – when something is wrong – the single next step to fix it.

Usage

hal_status()

Details

This is the first thing to run when hal misbehaves, and the thing to paste into a bug report.

Value

Invisibly, a list with elements backend, backend_source, available, detail, session_active, model, and next_step (NULL when everything is ready).

See Also

hal_setup(), hal_available(), hal_bridge_status(), hal_config()

Examples

## Not run: 
hal_status()

## End(Not run)

Description

Converts an R function into a hal tool definition suitable for ⁠$register_tool()⁠. Infers parameter types from function formals; override with the types argument for non-string parameters.

Usage

hal_tool(fn, name = NULL, description = NULL, types = NULL)

Arguments

Value

A list with name, description, fun, and parameters – ready for chat$register_tool().

Examples

my_sum <- function(x, y) x + y
tool <- hal_tool(my_sum, "add_numbers",
  description = "Add two numbers",
  types = list(x = "number", y = "number")
)
str(tool)
## Not run: 
# register on the active session so the model can call it
hal_register_tools(list(tool))

## End(Not run)

Description

An S3 class representing a single tool invocation by the agent. Tool calls appear inside hal_turn objects and are visible when printing conversation history.

Usage

## S3 method for class 'hal_tool_call'
format(x, ...)

## S3 method for class 'hal_tool_call'
print(x, ...)

Arguments

Value

The print() method returns x invisibly; the format() method returns a character scalar. hal_tool_call objects are created internally as tool activity streams in.

Fields

tool_call_id

Character: unique ID for this tool call.

title

Character: human-readable description (e.g., "Viewing DESCRIPTION").

kind

Character: tool kind ("read", "write", "command", etc.).

status

Character: "pending", "completed", or "failed".

input

Named list of input arguments.

output

Character: output text from the tool.

See Also

hal_turn, hal_response

Description

List Registered Tools

Usage

hal_tools()

Value

A character vector of tool names registered on the active session.

Examples

hal_tools()  # character(0) when no session is active

Description

An S3 class representing one turn in a hal conversation. Turns are returned by hal_history() and tracked internally by HalChat.

Usage

## S3 method for class 'hal_turn'
print(x, ...)

Arguments

Value

The print() method returns x invisibly. hal_turn objects themselves are created internally and returned by hal_history().

Fields

role

Character: "user", "assistant", or "system".

content

Character: text content of the turn.

tool_calls

List of hal_tool_call objects, or NULL.

thoughts

Character vector of agent thought chunks, or NULL.

See Also

hal_history(), hal_response, hal_tool_call

Description

Tallies hal() turns by model and, when tier info is available, computes cumulative Copilot billing units. Usage is tracked per session in memory and cleared by hal_reset().

Usage

hal_usage(tiers = NULL)

Arguments

Value

A hal_usage data frame with columns model, turns, tier, units (numeric tier × turns, NA if tier unknown). Prints a compact summary including the session total.

Examples

## Not run: 
hal("hello")
hal("follow-up", model = "gpt-4.1")
hal_usage()

## End(Not run)

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

HalChat$chat()

Send a message and get a response.

Usage

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

Arguments

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

HalChat$register_tools()

Register multiple tools.

Usage

HalChat$register_tools(tools)

Arguments

HalChat$get_turns()

Get conversation turns.

Usage

HalChat$get_turns(include_system_prompt = FALSE)

Arguments

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

Returns

Invisibly returns self.

HalChat$set_mode()

Set the session mode.

Usage

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

Arguments

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

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)

Description

Manages the Copilot CLI subprocess in ACP (Agent Client Protocol) mode and handles JSON-RPC 2.0 communication over NDJSON stdio. This is the low-level transport layer – most users should use HalChat instead.

The client spawns the Copilot CLI with --acp, which starts it as a JSON-RPC server. Authentication uses ambient Copilot credentials from any editor (VS Code, Positron, JetBrains).

Value

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

Methods

Public methods

• HalClient$new()

• HalClient$start()

• HalClient$stop()

• HalClient$register_tools()

• HalClient$handshake()

• HalClient$new_session()

• HalClient$prompt()

• HalClient$request()

• HalClient$notify()

• HalClient$switch_model()

• HalClient$set_mode()

• HalClient$get_session_id()

• HalClient$swap_session()

• HalClient$restore_session()

• HalClient$cancel()

• HalClient$set_ipc()

• HalClient$is_alive()

• HalClient$read_stderr()

• HalClient$clone()

HalClient$new()

Create a new Copilot SDK client.

Usage

HalClient$new(
  model = NULL,
  cli_path = NULL,
  permission_policy = "auto-allow",
  on_text = NULL,
  on_tool_call = NULL,
  on_thought = NULL,
  quiet = FALSE
)

Arguments

HalClient$start()

Start the Copilot CLI subprocess in ACP mode.

Usage

HalClient$start()

Returns

Invisibly returns self.

HalClient$stop()

Stop the Copilot CLI subprocess.

Usage

HalClient$stop()

HalClient$register_tools()

Register tools to expose via MCP server.

Tools must be registered before the first ⁠$prompt()⁠ call (before the CLI subprocess starts). The tools are passed via --additional-mcp-config at startup. Registering tools after the CLI is running triggers a warning.

Tools are merged into the existing set by name. Call multiple times to accumulate tools from different sources.

Usage

HalClient$register_tools(tools)

Arguments

Returns

Invisibly returns self.

HalClient$handshake()

Perform the ACP initialize handshake.

Sends the initialize request and initialized notification. Called automatically on first use if needed.

Usage

HalClient$handshake(timeout = 15)

Arguments

Returns

The initialize result (agent info and capabilities).

HalClient$new_session()

Create a new ACP session.

Sends session/new to create a session. The session holds conversation state server-side. Automatically performs the handshake if needed.

Custom tools are configured via --additional-mcp-config at CLI startup (not via mcpServers in this call, which is broken per CLI issue #1040).

Usage

HalClient$new_session(cwd = getwd(), timeout = 15)

Arguments

Returns

The session result (session ID, available models, modes).

HalClient$prompt()

Send a prompt and collect the streamed response.

Sends session/prompt and reads session/update notifications until the final response arrives. Automatically creates a session if needed.

Usage

HalClient$prompt(text, timeout = NULL)

Arguments

Returns

A hal_response with text, stop_reason, tool_calls, thoughts, and events.

HalClient$request()

Send a JSON-RPC request and wait for a response.

Usage

HalClient$request(method, params = list(), timeout = 60)

Arguments

Returns

Parsed JSON response result.

HalClient$notify()

Send a JSON-RPC notification (no response expected).

Usage

HalClient$notify(method, params = list())

Arguments

HalClient$switch_model()

Switch models mid-session.

Changes the active model without losing conversation context. Use hal_models() to see available model IDs.

Usage

HalClient$switch_model(model, timeout = 10)

Arguments

Returns

Invisibly returns self.

HalClient$set_mode()

Set the session mode.

Switches between Agent, Plan, and Autopilot modes.

• Agent: Default conversational mode.

• Plan: Multi-step planning mode with structured output.

• Autopilot: Autonomous mode that runs until task completion without user interaction (experimental).

Usage

HalClient$set_mode(mode = c("agent", "plan", "autopilot"), timeout = 10)

Arguments

Returns

Invisibly returns self.

HalClient$get_session_id()

Get the current session ID.

Usage

HalClient$get_session_id()

Returns

Character string, or NULL if no session is active.

HalClient$swap_session()

Create a temporary new session, saving the current one.

Used internally by disposable verbs (hal_ask) to get history isolation on the same CLI process. Call restore_session() to switch back.

Usage

HalClient$swap_session()

Returns

The saved (previous) session ID (invisibly).

HalClient$restore_session()

Restore a previously saved session ID.

Usage

HalClient$restore_session(session_id)

Arguments

Returns

Invisibly returns self.

HalClient$cancel()

Cancel the current in-flight prompt.

Signals the streaming loop to stop and return a partial response with stop_reason = "interrupted". Safe to call from callbacks, Shiny observers, or a second thread. Does nothing if no prompt is active.

For interactive use, pressing Ctrl+C (ESC in RStudio) during a prompt achieves the same effect automatically.

Usage

HalClient$cancel()

Returns

Invisibly returns self.

HalClient$set_ipc()

Configure IPC for live eval_r execution.

When set, the polling loop checks for eval_r requests from the MCP subprocess and executes them in the user's R session via eval_fn.

Usage

HalClient$set_ipc(ipc_dir, eval_fn = NULL, permission_fn = NULL)

Arguments

Returns

Invisibly returns self.

HalClient$is_alive()

Check if the client subprocess is running.

Usage

HalClient$is_alive()

Returns

Logical.

HalClient$read_stderr()

Read any available stderr output (for debugging).

Usage

HalClient$read_stderr()

Returns

Character string.

HalClient$clone()

The objects of this class are cloneable with this method.

Usage

HalClient$clone(deep = FALSE)

Arguments

See Also

HalChat for the high-level chat interface, hal_available() to check CLI availability.

Examples

## Not run: 
# Preferred: use hal_client()
client <- hal_client()
client$handshake()
session <- client$new_session()
client$stop()

## End(Not run)