Merge remote-tracking branch 'origin/main' into fix/harness-missing-return

Author: friggeri

.github/aw/github-agentic-workflows.md

@@ -214,18 +214,18 @@ The YAML frontmatter supports these fields:
     The `custom` engine allows you to define your own GitHub Actions steps instead of using an AI processor. Each step in the `steps` array follows standard GitHub Actions step syntax with `name`, `uses`/`run`, `with`, `env`, etc. This is useful for deterministic workflows that don't require AI processing.
 
     **Environment Variables Available to Custom Engines:**
-    
+
     Custom engine steps have access to the following environment variables:
-    
+
     - **`$GH_AW_PROMPT`**: Path to the generated prompt file (`/tmp/gh-aw/aw-prompts/prompt.txt`) containing the markdown content from the workflow. This file contains the natural language instructions that would normally be sent to an AI processor. Custom engines can read this file to access the workflow's markdown content programmatically.
     - **`$GH_AW_SAFE_OUTPUTS`**: Path to the safe outputs file (when safe-outputs are configured). Used for writing structured output that gets processed automatically.
     - **`$GH_AW_MAX_TURNS`**: Maximum number of turns/iterations (when max-turns is configured in engine config).
-    
+
     Example of accessing the prompt content:
     ```bash
     # Read the workflow prompt content
     cat $GH_AW_PROMPT
-    
+
     # Process the prompt content in a custom step
     - name: Process workflow instructions
       run: |
@@ -253,7 +253,7 @@ The YAML frontmatter supports these fields:
         log-level: debug                  # Optional: debug, info (default), warn, error
         args: ["--custom-arg", "value"]   # Optional: additional AWF arguments
     ```
-  
+
 - **`sandbox:`** - Sandbox configuration for AI engines (string or object)
   - String format: `"default"` (no sandbox), `"awf"` (Agent Workflow Firewall), `"srt"` or `"sandbox-runtime"` (Anthropic Sandbox Runtime)
   - Object format for full configuration:
@@ -703,7 +703,7 @@ cache:
     restore-keys: |
       node-modules-
   - key: build-cache-${{ github.sha }}
-    path: 
+    path:
       - dist
       - .cache
     restore-keys:
@@ -963,7 +963,7 @@ All other expressions are dissallowed.
 The `needs.activation.outputs.text` value provides automatically sanitized content based on the triggering event:
 
 - **Issues**: `title + "\n\n" + body`
-- **Pull Requests**: `title + "\n\n" + body`  
+- **Pull Requests**: `title + "\n\n" + body`
 - **Issue Comments**: `comment.body`
 - **PR Review Comments**: `comment.body`
 - **PR Reviews**: `review.body`
@@ -1163,7 +1163,7 @@ permissions:
 
 safe-outputs:
   create-issue:       # Automatic issue creation
-  add-comment:  # Automatic comment creation  
+  add-comment:  # Automatic comment creation
   create-pull-request: # Automatic PR creation
 ```
 
@@ -1437,7 +1437,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 
 **Supported Time Units:**
 - **Days**: `-1d`, `-7d`
-- **Weeks**: `-1w`, `-4w` 
+- **Weeks**: `-1w`, `-4w`
 - **Months**: `-1mo`, `-6mo`
 - **Hours/Minutes**: `-12h`, `-30m` (for sub-day precision)
 - **Combinations**: `-1mo2w3d`, `-2w5d12h`
@@ -1447,7 +1447,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 # Get runs from the last week
 gh aw logs --start-date -1w
 
-# Get runs up to yesterday  
+# Get runs up to yesterday
 gh aw logs --end-date -1d
 
 # Get runs from the last month
@@ -1502,7 +1502,7 @@ permissions:
 GitHub Agentic Workflows supports security scanning during compilation with `--actionlint`, `--zizmor`, and `--poutine` flags.
 
 **actionlint** - Lints GitHub Actions workflows and validates shell scripts with integrated shellcheck
-**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure  
+**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure
 **poutine** - Analyzes supply chain risks and third-party action usage
 
 ```bash
@@ -1559,7 +1559,7 @@ gh aw mcp list-tools github weekly-research
 
 This command is useful for:
 - **Discovering capabilities**: See what tools are available from each MCP server
-- **Workflow discovery**: Find which workflows use a specific MCP server  
+- **Workflow discovery**: Find which workflows use a specific MCP server
 - **Permission debugging**: Check which tools are allowed in your workflow configuration
 
 ## Compilation Process
@@ -1588,7 +1588,7 @@ Agentic workflows compile to GitHub Actions YAML:
 
 1. **Use descriptive workflow names** that clearly indicate purpose
 2. **Set appropriate timeouts** to prevent runaway costs
-3. **Include security notices** for workflows processing user content  
+3. **Include security notices** for workflows processing user content
 4. **Use the `imports:` field** in frontmatter for common patterns and security boilerplate
 5. **ALWAYS run `gh aw compile` after every change** to generate the GitHub Actions workflow (or `gh aw compile <workflow-id>` for specific workflows)
 6. **Review generated `.lock.yml`** files before deploying
@@ -1651,4 +1651,4 @@ gh aw logs <workflow-id>
 
 ### Documentation
 
-For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/
+For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/

.github/copilot-instructions.md

@@ -0,0 +1,53 @@
+# GitHub Copilot SDK — Assistant Instructions
+
+**Quick purpose:** Help contributors and AI coding agents quickly understand this mono-repo and be productive (build, test, add SDK features, add E2E tests). ✅
+
+## Big picture 🔧
+
+- The repo implements language SDKs (Node/TS, Python, Go, .NET) that speak to the **Copilot CLI** via **JSON‑RPC** (see `README.md` and `nodejs/src/client.ts`).
+- Typical flow: your App → SDK client → JSON-RPC → Copilot CLI (server mode). The CLI must be installed or you can connect to an external CLI server via the `CLI URL option (language-specific casing)` (Node: `cliUrl`, Go: `CLIUrl`, .NET: `CliUrl`, Python: `cli_url`).
+
+## Most important files to read first 📚
+
+- Top-level: `README.md` (architecture + quick start)
+- Language entry points: `nodejs/src/client.ts`, `python/README.md`, `go/README.md`, `dotnet/README.md`
+- Test harness & E2E: `test/harness/*`, Python harness wrapper `python/e2e/testharness/proxy.py`
+- Schemas & type generation: `nodejs/scripts/generate-session-types.ts`
+- Session snapshots used by E2E: `test/snapshots/` (used by the replay proxy)
+
+## Developer workflows (commands you’ll use often) ▶️
+
+- Monorepo helpers: use `just` tasks from repo root:
+  - Install deps: `just install` (runs npm ci, uv pip install -e, go mod download, dotnet restore)
+  - Format all: `just format` | Lint all: `just lint` | Test all: `just test`
+- Per-language:
+  - Node: `cd nodejs && npm ci` → `npm test` (Vitest), `npm run generate:session-types` to regenerate session-event types
+  - Python: `cd python && uv pip install -e ".[dev]"` → `uv run pytest` (E2E tests use the test harness)
+  - Go: `cd go && go test ./...`
+  - .NET: `cd dotnet && dotnet test test/GitHub.Copilot.SDK.Test.csproj`
+
+## Testing & E2E tips ⚙️
+
+- E2E runs against a local **replaying CAPI proxy** (see `test/harness/server.ts`). Most language E2E harnesses spawn that server automatically (see `python/e2e/testharness/proxy.py`).
+- Tests rely on YAML snapshot exchanges under `test/snapshots/` — to add test scenarios, add or edit the appropriate YAML files and update tests.
+- The harness prints `Listening: http://...` — tests parse this URL to configure CLI or proxy.
+
+## Project-specific conventions & patterns ✅
+
+- Tools: each SDK has helper APIs to expose functions as tools; prefer the language's `DefineTool`/`@define_tool`/`AIFunctionFactory.Create` patterns (see language READMEs).
+- Infinite sessions are enabled by default and persist workspace state to `~/.copilot/session-state/{sessionId}`; compaction events are emitted (`session.compaction_start`, `session.compaction_complete`). See language READMEs for usage.
+- Streaming: when `streaming`/`Streaming=true` you receive delta events (`assistant.message_delta`, `assistant.reasoning_delta`) and final events (`assistant.message`, `assistant.reasoning`) — tests expect this behavior.
+- Type generation is centralized in `nodejs/scripts/generate-session-types.ts` and requires the `@github/copilot` schema to be present (often via `npm link` or installed package).
+
+## Integration & environment notes ⚠️
+
+- The SDK requires a Copilot CLI installation or an external server reachable via the `CLI URL option (language-specific casing)` (Node: `cliUrl`, Go: `CLIUrl`, .NET: `CliUrl`, Python: `cli_url`) or `COPILOT_CLI_PATH`.
+- Some scripts (typegen, formatting) call external tools: `gofmt`, `dotnet format`, `tsx` (available via npm), `quicktype`/`quicktype-core` (used by the Node typegen script), and `prettier` (provided as an npm devDependency). Most of these are available through the repo's package scripts or devDependencies—run `just install` (and `cd nodejs && npm ci`) to install them. Ensure the required tools are available in CI / developer machines.
+- Tests may assume `node >= 18`, `python >= 3.9`, platform differences handled (Windows uses `shell=True` for npx in harness).
+
+## Where to add new code or tests 🧭
+
+- SDK code: `nodejs/src`, `python/copilot`, `go`, `dotnet/src`
+- Unit tests: `nodejs/test`, `python/*`, `go/*`, `dotnet/test`
+- E2E tests: `*/e2e/` folders that use the shared replay proxy and `test/snapshots/`
+- Generated types: update schema in `@github/copilot` then run `cd nodejs && npm run generate:session-types` and commit generated files in `src/generated` or language generated location.

.github/workflows/issue-triage.lock.yml

@@ -786,6 +786,113 @@ python weather_assistant.py
 
 </details>
 
+<details>
+<summary><strong>Go</strong></summary>
+
+Create `weather-assistant.go`:
+
+```go
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"log"
+	"math/rand"
+	"os"
+	"strings"
+
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+type WeatherParams struct {
+	City string `json:"city" jsonschema:"The city name"`
+}
+
+type WeatherResult struct {
+	City        string `json:"city"`
+	Temperature string `json:"temperature"`
+	Condition   string `json:"condition"`
+}
+
+func main() {
+	getWeather := copilot.DefineTool(
+		"get_weather",
+		"Get the current weather for a city",
+		func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
+			conditions := []string{"sunny", "cloudy", "rainy", "partly cloudy"}
+			temp := rand.Intn(30) + 50
+			condition := conditions[rand.Intn(len(conditions))]
+			return WeatherResult{
+				City:        params.City,
+				Temperature: fmt.Sprintf("%d°F", temp),
+				Condition:   condition,
+			}, nil
+		},
+	)
+
+	client := copilot.NewClient(nil)
+	if err := client.Start(); err != nil {
+		log.Fatal(err)
+	}
+	defer client.Stop()
+
+	session, err := client.CreateSession(&copilot.SessionConfig{
+		Model:     "gpt-4.1",
+		Streaming: true,
+		Tools:     []copilot.Tool{getWeather},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	session.On(func(event copilot.SessionEvent) {
+		if event.Type == "assistant.message_delta" {
+			if event.Data.DeltaContent != nil {
+				fmt.Print(*event.Data.DeltaContent)
+			}
+		}
+		if event.Type == "session.idle" {
+			fmt.Println()
+		}
+	})
+
+	fmt.Println("🌤️  Weather Assistant (type 'exit' to quit)")
+	fmt.Println("   Try: 'What's the weather in Paris?' or 'Compare weather in NYC and LA'\n")
+
+	scanner := bufio.NewScanner(os.Stdin)
+	for {
+		fmt.Print("You: ")
+		if !scanner.Scan() {
+			break
+		}
+		input := scanner.Text()
+		if strings.ToLower(input) == "exit" {
+			break
+		}
+
+		fmt.Print("Assistant: ")
+		_, err = session.SendAndWait(copilot.MessageOptions{Prompt: input}, 0)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			break
+		}
+		fmt.Println()
+	}
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "Input error: %v\n", err)
+	}
+}
+```
+
+Run with:
+
+```bash
+go run weather-assistant.go
+```
+
+</details>
+
 <details>
 <summary><strong>.NET</strong></summary>
 
@@ -954,10 +1061,10 @@ By default, the SDK automatically manages the Copilot CLI process lifecycle, sta
 
 ### Running the CLI in Server Mode
 
-Start the CLI in server mode using the `--server` flag and optionally specify a port:
+Start the CLI in server mode using the `--headless` flag and optionally specify a port:
 
 ```bash
-copilot --server --port 4321
+copilot --headless --port 4321
 ```
 
 If you don't specify a port, the CLI will choose a random available port.