Skip to content

fix: broaden engine.driver schema description to match runtime multi-language support #44355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Jul 9, 2026
+9 −6
Merged

fix: broaden engine.driver schema description to match runtime multi-language support #44355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
471107e
Initial plan
Copilot Jul 8, 2026
98d0d48
fix: broaden engine.driver schema description to match runtime multi-…
Copilot Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions docs/src/content/docs/reference/frontmatter-full.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2320,11 +2320,14 @@ engine:
# (optional)
copilot-sdk: true

# Custom inner driver script for engines that support driver mode (e.g. pi).
# Accepts a workspace-relative path ending with .js, .cjs, or .mjs (e.g.
# `.github/drivers/pi_agent_core_driver_sample_node.cjs`), or a bare filename
# without a path separator resolved from the gh-aw setup-action directory (e.g.
# `pi_agent_core_driver.cjs`).
# Custom driver script or command for the engine. Accepts a workspace-relative
# path or bare name. Supported extensions depend on the engine: the copilot
# engine accepts .js, .cjs, .mjs (Node.js), .py (Python), .ts or .mts
# (TypeScript), or .rb (Ruby); other engines (e.g. pi) accept .js, .cjs, or
# .mjs only. A bare name without an extension is also valid for any engine
# (treated as a built-in driver or executable in PATH). Examples:

@github-actions github-actions Bot Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/grill-with-docs] The phrase "executable in PATH" is inaccurate for the pi engine — it drops a correct detail from the original docs and contradicts the internal implementation.

💡 Details and suggested fix

Per buildPiDriverCommand() in pkg/workflow/pi_engine.go (line 562–572) and the Driver field comment in pkg/workflow/engine.go (line 61), a bare name for the pi engine is resolved from the setup-action directory (${RUNNER_TEMP}/gh-aw/actions/<name>), not from PATH. Only the copilot engine treats bare names as arbitrary PATH executables.

The original docs correctly said:

a bare filename without a path separator resolved from the gh-aw setup-action directory

Suggested replacement for the last comment line before the (optional) marker:

  # (treated as a built-in driver from the setup-action directory for the pi engine,
  # or as an executable in PATH for the copilot engine). Examples:

This preserves the accurate per-engine distinction that was lost in the rewrite.

@copilot please address this.

@github-actions github-actions Bot Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Factual error: bare names for the pi engine are not resolved from PATH — they resolve from the setup-action directory (${RUNNER_TEMP}/gh-aw/actions/<name>).

💡 Details and suggested fix

What the runtime actually does

pi_engine.go::buildPiDriverCommand uses this logic for bare names (no / in the name):

// no "/" → resolve from setup-action directory
driverPath = fmt.Sprintf(`"%s/%s"`, SetupActionDestinationShell, driverName)

So pi_agent_core_driver.cjs resolves to ${RUNNER_TEMP}/gh-aw/actions/pi_agent_core_driver.cjs, not $PATH.

The old wording was correct: "resolved from the gh-aw setup-action directory."

The copilot engine does treat bare names (no extension) as arbitrary executables in PATH — but the updated text accidentally generalises this to "any engine", which is wrong for pi.

Suggested wording

# A bare name without an extension is also valid: for the copilot engine it is
# treated as an arbitrary executable in PATH; for other engines (e.g. pi) it is
# resolved from the gh-aw setup-action directory.

# `.github/drivers/my_driver.cjs`, `.github/drivers/my_driver.py`,
# `my-copilot-driver`.
Comment on lines +2327 to +2330
# (optional)
driver: "example-value"

Expand Down
2 changes: 1 addition & 1 deletion pkg/parser/schemas/main_workflow_schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12415,7 +12415,7 @@
"driver": {
"type": "string",
"pattern": "^(?:(?:\\.[A-Za-z0-9_]|[A-Za-z0-9_])[A-Za-z0-9._-]*)(?:/(?:(?:\\.[A-Za-z0-9_]|[A-Za-z0-9_])[A-Za-z0-9._-]*))*$",
"description": "Custom inner driver script for engines that support driver mode (e.g. pi). Accepts a workspace-relative path ending with .js, .cjs, or .mjs (e.g. `.github/drivers/pi_agent_core_driver_sample_node.cjs`), or a bare filename without a path separator resolved from the gh-aw setup-action directory (e.g. `pi_agent_core_driver.cjs`)."
"description": "Custom driver script or command for the engine. Accepts a workspace-relative path or bare name. Supported extensions depend on the engine: the copilot engine accepts .js, .cjs, .mjs (Node.js), .py (Python), .ts or .mts (TypeScript), or .rb (Ruby); other engines (e.g. pi) accept .js, .cjs, or .mjs only. A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH). Examples: `.github/drivers/my_driver.cjs`, `.github/drivers/my_driver.py`, `my-copilot-driver`."

@github-actions github-actions Bot Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/grill-with-docs] Same bare-name accuracy issue: the schema description says bare names are treated as "executable in PATH" for any engine, but for the pi engine they are resolved from the setup-action directory.

💡 Suggested wording

Current:

A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH).

Suggested:

A bare name without an extension is also valid for any engine (for the pi engine, resolved from the gh-aw setup-action directory; for the copilot engine, resolved as an executable in PATH).

This aligns the JSON schema description with the runtime behaviour in buildPiDriverCommand() and the field-level comment in engine.go.

@copilot please address this.

@github-actions github-actions Bot Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Schema description does not match docs: the engine.driver description in main_workflow_schema.json now says bare names are valid for "any engine (treated as a built-in driver or executable in PATH)" — same as the docs comment — but for the pi engine a bare name resolves from the setup-action directory, not PATH.

💡 Details

The JSON Schema description on line 34 of the diff says:

A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH).

This is accurate for the copilot engine, but for the pi engine pi_engine.go::buildPiDriverCommand resolves bare names as:

driverPath = fmt.Sprintf(`"%s/%s"`, SetupActionDestinationShell, driverName)

i.e., ${RUNNER_TEMP}/gh-aw/actions/<name> — not from PATH. Schema descriptions are used by IDEs/tooling as inline help; this misleads pi-engine users about where their driver will be looked up.

Suggested replacement for the bare-name clause:

A bare name without an extension is also valid: for the copilot engine it is treated as an arbitrary executable in PATH; for other engines (e.g. pi) it is resolved from the gh-aw setup-action directory.

},
"extensions": {
"type": "array",
Expand Down
Loading