Source: openaf-opacks 87b07e97. See documentation baseline for availability and verification.

Build and test commands use the package’s source directory; installation and library examples use the installed oPack.

ghcopilot opack

OpenAF wrapper around the official GitHub Java SDK copilot-sdk-java as an ow.ai LLM provider named ghcopilot.

Requirements

  • Java 17+
  • GitHub Copilot CLI installed and available in PATH (or configured with cliPath)
  • Valid Copilot authentication on the local machine, or a token

Compatibility note

This opack currently wraps the official GitHub Java SDK shipped in this folder. If you see an error like:

SDK protocol version mismatch: SDK expects version 2, but server reports version 3

your local copilot CLI/server is newer than the bundled Java SDK protocol. In that case, either:

  • point options.cliPath at an older compatible copilot binary
  • pin/downgrade the installed @github/copilot CLI to a compatible version
  • update the bundled Java SDK when upstream adds support for the newer protocol

Check the active CLI with:

copilot --version

Model “X” is not available (but works in the interactive CLI)

If createSession/prompt fails with an error like:

Model "gpt-5.6-luna" is not available.

even though the same model works when you run copilot interactively, this is usually an authentication identity mismatch, not a stale/unsupported model. getModels() lists the general Copilot model catalog, but session.create validates the requested model against whichever identity the spawned copilot process actually authenticates as — and new/preview models are often gated per-account (plan tier, org policy, preview enrollment).

When token/githubToken is set, the SDK exports it to the Copilot subprocess as COPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKEN, so the process authenticates as that token’s identity instead of reusing your interactively logged-in copilot session — and that token’s identity may not have the same model entitlements.

Fixes:

  • Set useLoggedInUser: true and drop token/githubToken so the SDK reuses your existing copilot auth login session, or
  • Refresh/re-authenticate the token being used, e.g. gh auth refresh

Install GitHub Copilot CLI

Use one of the following options:

npm (direct install) 

npm install -g @github/copilot

GitHub CLI extension 

gh extension install github/gh-copilot

After installation, confirm the binary is available:

copilot --version

Authenticate with one of the following:

copilot auth login

or export a token for non-interactive use:

export GITHUB_TOKEN=...

Install Java dependencies

From this folder run:

ojob ojob.io/oaf/mavenGetJars folder=.

Usage 

loadLib("ghcopilot.js")

var llm = ow.ai.llm({
  type: "ghcopilot",
  options: {
    model: "gpt-4.1",
    timeout: 120000,
    useStdio: true,
    excludeAllExistingTools: true,
    token: "<github-token>"
  }
})

llm.addSystemPrompt("You are concise.")
print(llm.prompt("Say hello in one sentence."))

var streamed = llm.promptStream("Count from 1 to 3.", __, __, false, __, (chunk, full) => {
  printnl(chunk)
})
print("\nFinal: " + streamed)

oaf_model / OAFP_MODEL definition

You can define this provider in OAFP_MODEL / OAF_MODEL using token to authenticate the Copilot CLI process:

type: ghcopilot
options:
  model: gpt-4.1
  token: ${GITHUB_TOKEN}
  timeout: 120000
  useStdio: true

token is forwarded to the SDK and also exported to the Copilot process as COPILOT_GITHUB_TOKEN, GH_TOKEN, and GITHUB_TOKEN.

You can also set the model in OpenAF directly with:

export OAF_MODEL="(type: ghcopilot, options: (model: gpt-4.1, timeout: 900000, token: $(gh auth token)))"

Tool use

Register tools with setTool before prompting. The SDK’s native ToolDefinition / ToolHandler mechanism is used, so the Copilot agent calls tools automatically while processing the request:

llm.setTool(
  "get_time",
  "Returns the current UTC time as an ISO-8601 string",
  { type: "object", properties: {}, required: [] },
  (args) => new Date().toISOString()
)
print(llm.prompt("What time is it right now?"))

Adding or removing tools causes the session to be transparently recreated on the next call.

Options

  • params (map, optional): Reserved for provider/API compatibility. Keep empty unless another integration explicitly requires it.
  • model (string, default: gpt-4.1): Model ID used for generation (for example gpt-4.1, gpt-4o, etc.).
  • timeout (number in ms, default: 120000): Maximum wait time for a response before the request is aborted.
  • mode (string, optional): Send scheduling mode (enqueue or immediate). For compatibility, agent-mode values supplied here are routed to agentMode.
  • agentMode (string, optional): Copilot agent mode: interactive, plan, autopilot, or shell.
  • token (string, optional): Preferred authentication token for Copilot CLI sessions.
  • githubToken (string, optional): Legacy alias for token (use token in new configs).
  • cliPath (string, optional): Absolute path to the copilot executable when it is not available in PATH.
  • cliUrl (string, optional): Optional CLI endpoint/URL used by the SDK when supported by your setup.
  • cwd (string, optional): Working directory used by the Copilot process (affects file/tool context).
  • useStdio (boolean, default: true): Communicates with Copilot CLI over stdio (recommended/default transport).
  • autoStart (boolean, default: true): Automatically starts a CLI session on first request.
  • autoRestart (boolean, default: false): Automatically recreates the session after failures or disconnects.
  • useLoggedInUser (boolean, optional): Prefer the local Copilot logged-in account/session instead of explicit token-only auth. Set this to true if a model works in the interactive copilot CLI but session creation reports it as unavailable — see Model “X” is not available.
  • logLevel (string, optional): SDK/CLI logging verbosity for troubleshooting (for example debug, info, warn, error).
  • reasoningEffort (string, optional): Reasoning intensity hint forwarded to SessionConfig.setReasoningEffort.
  • configDir (string, optional): Custom configuration directory forwarded to SessionConfig.setConfigDir.
  • onPermissionRequest (internal, default: PermissionHandler.APPROVE_ALL): Session permission requests are auto-approved by default to satisfy SDK session creation requirements.
  • skillDirectories (array of strings, optional): Additional directories where Copilot skills are loaded from.
  • disabledSkills (array of strings, optional): Skill IDs/names to disable, even if available in configured skill directories.
  • availableTools (array of strings, optional): Allowlist of built-in tools the agent is permitted to call.
  • excludedTools (array of strings, optional): Blocklist of built-in tools that must not be called.
  • excludeAllExistingTools (boolean, default: true): Disables all built-in Copilot tools for the session while still allowing tools registered with setTool(...).

All available options

The following options are supported:

  • params
  • model
  • timeout
  • mode
  • agentMode
  • token
  • githubToken
  • cliPath
  • cliUrl
  • cwd
  • useStdio
  • autoStart
  • autoRestart
  • useLoggedInUser
  • logLevel
  • reasoningEffort
  • configDir
  • onPermissionRequest
  • skillDirectories
  • disabledSkills
  • availableTools
  • excludedTools
  • excludeAllExistingTools

Additional methods

Along with the standard ow.ai.gpt surface, this provider also exposes:

  • getModels()
  • getAuthStatus() (authenticated state, login, host, authentication type, and status message; no token)
  • getLastStats()
  • promptWithStats(...)
  • rawPromptWithStats(...)
  • promptStreamWithStats(...)
  • rawPromptStreamWithStats(...)
  • close()

getModels() returns the Copilot SDK model list with id and name plus available SDK metadata, including policy, capabilities, billing, supportedReasoningEfforts, and defaultReasoningEffort. Use policy.state to inspect model availability/entitlement hints when a model appears in the list but session.create rejects it — and check the authentication identity in use, since getModels() reflects the general catalog regardless of which account will actually authenticate the session (see Model “X” is not available).

Troubleshooting account-dependent timeouts

Text, streaming, and image requests use session.send() and correlate response events with its returned message ID. For CLI event schemas that omit correlation IDs, the submitted prompt is matched against the root user-message content, then its assistant response is collected. Explicit mismatched IDs remain excluded. Use one prompt at a time per provider instance. Requests complete on the root session idle event, avoiding a stalled SDK session.sendAndWait completion RPC. The configured timeout covers both send acknowledgement and event completion. A timed-out request triggers a best-effort abort (up to one additional second waiting for acknowledgement) and retires its session; the next prompt creates a new session.

Use getAuthStatus() on the provider to compare the authenticated login and host between environments. Explicit token/githubToken options take precedence over inherited token environment variables for the spawned CLI. Without an explicit token, the CLI’s normal authentication precedence applies. When using cliUrl, authentication also depends on the externally managed CLI server.

setDebugCh("copilot-debug") additionally records session creation errors, session event types, and request errors with elapsed time and the last observed event. Debug channels also contain prompts and responses, so treat them as sensitive. These diagnostics do not change account entitlements or organization policy; a supported token and Copilot access are still required.

Docker

A sample Dockerfile is included in this folder and is based on openaf/oaf:edge-t8, adding Node.js/npm plus the @github/copilot binary.

Build the image, export OAF_MODEL, and then run the container with that environment variable:

docker build -t my-image .
export OAF_MODEL="(type: ghcopilot, options: (model: gpt-4.1, timeout: 900000, token: $(gh auth token)))"
docker run --rm -ti -e OAF_MODEL=$OAF_MODEL my-image

Notes

  • This opack uses the Java SDK send flow with correlated response and idle events.
  • aJsonFlag=true appends a JSON-only instruction and attempts to parse the answer.
  • Provider API compatibility with ow.ai.gpt now includes setDebugCh(aChName), promptImage(...), promptStream(...), getModelInfo(aModelId), exportConversation(), and importConversation(...).

Dependency refresh (2026-10-09)

The 20261009 local package bundles copilot-sdk-java 1.0.18-preview.4, matching the SDK already shipped on master. The Maven maintenance configuration holds this preview version explicitly because automatic discovery selects stable releases only. Copilot authentication and CLI/server compatibility still need to be verified in the target environment.

This site uses Just the Docs, a documentation theme for Jekyll.