@oar-sh/oar 0.9.0

package/server/uploads/image_input.md

@@ -0,0 +1,540 @@
+# Image input
+
+Send images to Copilot sessions as attachments. There are two ways to attach images:
+
+* **File attachment** (`type: "file"`): provide an absolute path; the runtime reads the file from disk, converts it to base64, and sends it to the LLM.
+* **Blob attachment** (`type: "blob"`): provide base64-encoded data directly; useful when the image is already in memory (e.g., screenshots, generated images, or data from an API).
+
+## Overview
+
+```mermaid
+sequenceDiagram
+    participant App as Your App
+    participant SDK as SDK Session
+    participant RT as Copilot Runtime
+    participant LLM as Vision Model
+
+    App->>SDK: send({ prompt, attachments: [{ type: "file", path }] })
+    SDK->>RT: JSON-RPC with file attachment
+    RT->>RT: Read file from disk
+    RT->>RT: Detect image, convert to base64
+    RT->>RT: Resize if needed (model-specific limits)
+    RT->>LLM: image_url content block (base64)
+    LLM-->>RT: Response referencing the image
+    RT-->>SDK: assistant.message events
+    SDK-->>App: event stream
+```
+
+| Concept | Description |
+|---------|-------------|
+| **File attachment** | An attachment with `type: "file"` and an absolute `path` to an image on disk |
+| **Blob attachment** | An attachment with `type: "blob"`, base64-encoded `data`, and a `mimeType`—no disk I/O needed |
+| **Automatic encoding** | For file attachments, the runtime reads the image and converts it to base64 automatically |
+| **Auto-resize** | The runtime automatically resizes or quality-reduces images that exceed model-specific limits |
+| **Vision capability** | The model must have `capabilities.supports.vision = true` to process images |
+
+## Quick start—file attachment
+
+Attach an image file to any message using the file attachment type. The path must be an absolute path to an image on disk.
+
+<details open>
+<summary><strong>Node.js / TypeScript</strong></summary>
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+    model: "gpt-4.1",
+    onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+await session.send({
+    prompt: "Describe what you see in this image",
+    attachments: [
+        {
+            type: "file",
+            path: "/absolute/path/to/screenshot.png",
+        },
+    ],
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Python</strong></summary>
+
+```python
+from copilot import CopilotClient
+from copilot.session import PermissionRequestResult
+
+client = CopilotClient()
+await client.start()
+
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+)
+
+await session.send(
+    "Describe what you see in this image",
+    attachments=[
+        {
+            "type": "file",
+            "path": "/absolute/path/to/screenshot.png",
+        },
+    ],
+)
+```
+
+</details>
+
+<details>
+<summary><strong>Go</strong></summary>
+
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import (
+	"context"
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	client := copilot.NewClient(nil)
+	client.Start(ctx)
+
+	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+		Model: "gpt-4.1",
+		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+			return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+		},
+	})
+
+	path := "/absolute/path/to/screenshot.png"
+	session.Send(ctx, copilot.MessageOptions{
+		Prompt: "Describe what you see in this image",
+		Attachments: []copilot.Attachment{
+            &copilot.UserMessageAttachmentFile{
+                DisplayName: "screenshot.png",
+                Path:        path,
+			},
+		},
+	})
+}
+```
+<!-- /docs-validate: hidden -->
+
+```go
+ctx := context.Background()
+client := copilot.NewClient(nil)
+client.Start(ctx)
+
+session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+    Model: "gpt-4.1",
+    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+        return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+    },
+})
+
+path := "/absolute/path/to/screenshot.png"
+session.Send(ctx, copilot.MessageOptions{
+    Prompt: "Describe what you see in this image",
+    Attachments: []copilot.Attachment{
+        &copilot.UserMessageAttachmentFile{
+            DisplayName: "screenshot.png",
+            Path:        path,
+        },
+    },
+})
+```
+
+</details>
+
+<details>
+<summary><strong>.NET</strong></summary>
+
+<!-- docs-validate: hidden -->
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class ImageInputExample
+{
+    public static async Task Main()
+    {
+        await using var client = new CopilotClient();
+        await using var session = await client.CreateSessionAsync(new SessionConfig
+        {
+            Model = "gpt-4.1",
+            OnPermissionRequest = (req, inv) =>
+                Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+        });
+
+        await session.SendAsync(new MessageOptions
+        {
+            Prompt = "Describe what you see in this image",
+            Attachments = new List<UserMessageAttachment>
+            {
+                new UserMessageAttachmentFile
+                {
+                    Path = "/absolute/path/to/screenshot.png",
+                    DisplayName = "screenshot.png",
+                },
+            },
+        });
+    }
+}
+```
+<!-- /docs-validate: hidden -->
+
+```csharp
+using GitHub.Copilot.SDK;
+
+await using var client = new CopilotClient();
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Model = "gpt-4.1",
+    OnPermissionRequest = (req, inv) =>
+        Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+});
+
+await session.SendAsync(new MessageOptions
+{
+    Prompt = "Describe what you see in this image",
+    Attachments = new List<UserMessageAttachment>
+    {
+        new UserMessageAttachmentFile
+        {
+            Path = "/absolute/path/to/screenshot.png",
+            DisplayName = "screenshot.png",
+        },
+    },
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.List;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setModel("gpt-4.1")
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    session.send(new MessageOptions()
+        .setPrompt("Describe what you see in this image")
+        .setAttachments(List.of(
+            new Attachment("file", "/absolute/path/to/screenshot.png", "screenshot.png")
+        ))
+    ).get();
+}
+```
+
+</details>
+
+## Quick start—blob attachment
+
+When you already have image data in memory (e.g., a screenshot captured by your app, or an image fetched from an API), use a blob attachment to send it directly without writing to disk.
+
+<details open>
+<summary><strong>Node.js / TypeScript</strong></summary>
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+    model: "gpt-4.1",
+    onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+const base64ImageData = "..."; // your base64-encoded image
+await session.send({
+    prompt: "Describe what you see in this image",
+    attachments: [
+        {
+            type: "blob",
+            data: base64ImageData,
+            mimeType: "image/png",
+            displayName: "screenshot.png",
+        },
+    ],
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Python</strong></summary>
+
+```python
+from copilot import CopilotClient
+from copilot.session import PermissionRequestResult
+
+client = CopilotClient()
+await client.start()
+
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+)
+
+base64_image_data = "..."  # your base64-encoded image
+await session.send(
+    "Describe what you see in this image",
+    attachments=[
+        {
+            "type": "blob",
+            "data": base64_image_data,
+            "mimeType": "image/png",
+            "displayName": "screenshot.png",
+        },
+    ],
+)
+```
+
+</details>
+
+<details>
+<summary><strong>Go</strong></summary>
+
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import (
+	"context"
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	client := copilot.NewClient(nil)
+	client.Start(ctx)
+
+	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+		Model: "gpt-4.1",
+		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+			return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+		},
+	})
+
+	base64ImageData := "..."
+	mimeType := "image/png"
+	displayName := "screenshot.png"
+	session.Send(ctx, copilot.MessageOptions{
+		Prompt: "Describe what you see in this image",
+		Attachments: []copilot.Attachment{
+            &copilot.UserMessageAttachmentBlob{
+                Data:        base64ImageData,
+                MIMEType:    mimeType,
+				DisplayName: &displayName,
+			},
+		},
+	})
+}
+```
+<!-- /docs-validate: hidden -->
+
+```go
+mimeType := "image/png"
+displayName := "screenshot.png"
+session.Send(ctx, copilot.MessageOptions{
+    Prompt: "Describe what you see in this image",
+    Attachments: []copilot.Attachment{
+        &copilot.UserMessageAttachmentBlob{
+            Data:        base64ImageData, // base64-encoded string
+            MIMEType:    mimeType,
+            DisplayName: &displayName,
+        },
+    },
+})
+```
+
+</details>
+
+<details>
+<summary><strong>.NET</strong></summary>
+
+<!-- docs-validate: hidden -->
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class BlobAttachmentExample
+{
+    public static async Task Main()
+    {
+        await using var client = new CopilotClient();
+        await using var session = await client.CreateSessionAsync(new SessionConfig
+        {
+            Model = "gpt-4.1",
+            OnPermissionRequest = (req, inv) =>
+                Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+        });
+
+        var base64ImageData = "...";
+        await session.SendAsync(new MessageOptions
+        {
+            Prompt = "Describe what you see in this image",
+            Attachments = new List<UserMessageAttachment>
+            {
+                new UserMessageAttachmentBlob
+                {
+                    Data = base64ImageData,
+                    MimeType = "image/png",
+                    DisplayName = "screenshot.png",
+                },
+            },
+        });
+    }
+}
+```
+<!-- /docs-validate: hidden -->
+
+```csharp
+await session.SendAsync(new MessageOptions
+{
+    Prompt = "Describe what you see in this image",
+    Attachments = new List<UserMessageAttachment>
+    {
+        new UserMessageAttachmentBlob
+        {
+            Data = base64ImageData,
+            MimeType = "image/png",
+            DisplayName = "screenshot.png",
+        },
+    },
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+import java.util.List;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setModel("gpt-4.1")
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    var base64ImageData = "..."; // your base64-encoded image
+    session.send(new MessageOptions()
+        .setPrompt("Describe what you see in this image")
+        .setAttachments(List.of(
+            new BlobAttachment()
+                .setData(base64ImageData)
+                .setMimeType("image/png")
+                .setDisplayName("screenshot.png")
+        ))
+    ).get();
+}
+```
+
+</details>
+
+## Supported formats
+
+Supported image formats include JPG, PNG, GIF, and other common image types. For file attachments, the runtime reads the image from disk and converts it as needed. For blob attachments, you provide the base64 data and MIME type directly. Use PNG or JPEG for best results, as these are the most widely supported formats.
+
+The model's `capabilities.limits.vision.supported_media_types` field lists the exact MIME types it accepts.
+
+## Automatic processing
+
+The runtime automatically processes images to fit within the model's constraints. No manual resizing is required.
+
+* Images that exceed the model's dimension or size limits are automatically resized (preserving aspect ratio) or quality-reduced.
+* If an image cannot be brought within limits after processing, it is skipped and not sent to the LLM.
+* The model's `capabilities.limits.vision.max_prompt_image_size` field indicates the maximum image size in bytes.
+
+You can check these limits at runtime via the model capabilities object. For the best experience, use reasonably-sized PNG or JPEG images.
+
+## Vision model capabilities
+
+Not all models support vision. Check the model's capabilities before sending images.
+
+### Capability fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capabilities.supports.vision` | `boolean` | Whether the model can process image inputs |
+| `capabilities.limits.vision.supported_media_types` | `string[]` | MIME types the model accepts (e.g., `["image/png", "image/jpeg"]`) |
+| `capabilities.limits.vision.max_prompt_images` | `number` | Maximum number of images per prompt |
+| `capabilities.limits.vision.max_prompt_image_size` | `number` | Maximum image size in bytes |
+
+### Vision limits type
+
+<!-- docs-validate: hidden -->
+```typescript
+interface VisionCapabilities {
+    vision?: {
+        supported_media_types: string[];
+        max_prompt_images: number;
+        max_prompt_image_size: number; // bytes
+    };
+}
+```
+<!-- /docs-validate: hidden -->
+```typescript
+vision?: {
+    supported_media_types: string[];
+    max_prompt_images: number;
+    max_prompt_image_size: number; // bytes
+};
+```
+
+## Receiving image results
+
+When tools return images (e.g., screenshots or generated charts), the result contains `"image"` content blocks with base64-encoded data.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"image"` | Content block type discriminator |
+| `data` | `string` | Base64-encoded image data |
+| `mimeType` | `string` | MIME type (e.g., `"image/png"`) |
+
+These image blocks appear in `tool.execution_complete` event results. See the [Streaming Events](./streaming-events.md) guide for the full event lifecycle.
+
+## Tips and limitations
+
+| Tip | Details |
+|-----|---------|
+| **Use PNG or JPEG directly** | Avoids conversion overhead—these are sent to the LLM as-is |
+| **Keep images reasonably sized** | Large images may be quality-reduced, which can lose important details |
+| **Use absolute paths for file attachments** | The runtime reads files from disk; relative paths may not resolve correctly |
+| **Use blob attachments for in-memory data** | When you already have base64 data (e.g., screenshots, API responses), blob avoids unnecessary disk I/O |
+| **Check vision support first** | Sending images to a non-vision model wastes tokens without visual understanding |
+| **Multiple images are supported** | Attach several attachments in one message, up to the model's `max_prompt_images` limit |
+| **SVG is not supported** | SVG files are text-based and excluded from image processing |
+
+## See also
+
+* [Streaming Events](./streaming-events.md): event lifecycle including tool result content blocks
+* [Steering & Queueing](./steering-and-queueing.md): sending follow-up messages with attachments

package/server/windows-terminal-launcher.mjs

@@ -0,0 +1,29 @@
+'use strict';
+
+import { createHash } from 'crypto';
+import path from 'path';
+
+function normalizeWorkspaceRoot(workspaceRoot) {
+  return path.resolve(String(workspaceRoot || '').trim() || process.cwd());
+}
+
+export function buildWindowsTerminalWindowName(workspaceRoot, prefix = 'copilot-relay') {
+  const normalizedRoot = normalizeWorkspaceRoot(workspaceRoot).replace(/[\\/]+/g, '/').toLowerCase();
+  const fingerprint = createHash('sha256').update(normalizedRoot).digest('hex').slice(0, 12);
+  return `${prefix}-${fingerprint}`;
+}
+
+export function buildWindowsTerminalForegroundArgs({
+  workspaceRoot,
+  windowName,
+  title = 'Copilot Relay',
+  commandPath,
+  commandArgs = [],
+}) {
+  const args = ['-w', String(windowName || '').trim()];
+  args.push('new-tab');
+  args.push('--startingDirectory', normalizeWorkspaceRoot(workspaceRoot));
+  args.push('--title', String(title || '').trim() || 'Copilot Relay');
+  args.push(commandPath, ...commandArgs);
+  return args;
+}

package/server/workspace-root.mjs

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+
+import { normalizeDriveLetterOnlyPath } from './services/workspace-root-path-policy.mjs';
+
+// Mirrors workspace-root-path-policy.mjs: the platform is a parameter, never an
+// implicit read of the host, so win32 `cd` semantics stay testable off Windows.
+function pathFor(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+function isDirectory(targetPath) {
+  try {
+    return fs.statSync(targetPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveWorkspaceRootPath(preferredRoot, fallbackRoot) {
+  const candidates = [preferredRoot, fallbackRoot];
+  for (const candidate of candidates) {
+    const value = String(candidate || '').trim();
+    if (!value) continue;
+    const resolved = path.resolve(value);
+    if (isDirectory(resolved)) return resolved;
+  }
+  return path.resolve(String(fallbackRoot || process.cwd()).trim() || process.cwd());
+}
+
+export function resolveRepositoryWorkspaceRoot(preferredRoot, scriptDir) {
+  const repoRoot = path.resolve(String(scriptDir || '').trim() || process.cwd(), '..');
+  return resolveWorkspaceRootPath(preferredRoot, repoRoot);
+}
+
+export function resolveStartupWorkspaceRoot(scriptDir, preferredRoot = process.env.COPILOT_WORKSPACE_ROOT || process.cwd()) {
+  return resolveRepositoryWorkspaceRoot(preferredRoot, scriptDir);
+}
+
+export function workspaceRootDisplayName(rootPath) {
+  const resolved = path.resolve(String(rootPath || '').trim() || process.cwd());
+  const base = path.basename(resolved);
+  if (base) return base;
+  const driveRoot = path.parse(resolved).root;
+  return driveRoot || 'workspace';
+}
+
+export function parseCdCommandTarget(text) {
+  const source = String(text || '').trim();
+  if (!source || source.includes('\n') || source.includes('\r')) return null;
+
+  const match = /^cd(?:\s+\/d)?(?:\s+(.+))?$/i.exec(source);
+  if (!match) return null;
+
+  let target = String(match[1] || '').trim();
+  if (!target) return null;
+
+  if (
+    (target.startsWith('"') && target.endsWith('"'))
+    || (target.startsWith("'") && target.endsWith("'"))
+  ) {
+    target = target.slice(1, -1).trim();
+  }
+  if (!target) return null;
+  if (/[;&|]/.test(target)) return null;
+  return target;
+}
+
+export function resolveCdCommandPath(
+  targetPath,
+  currentRoot,
+  homeDir = process.env.USERPROFILE || process.env.HOME || process.cwd(),
+  platform = process.platform,
+) {
+  const pathApi = pathFor(platform);
+  let candidate = normalizeDriveLetterOnlyPath(targetPath);
+  if (!candidate) return null;
+
+  if (candidate === '~') {
+    candidate = homeDir;
+  } else if (candidate.startsWith('~/') || candidate.startsWith('~\\')) {
+    candidate = pathApi.join(homeDir, candidate.slice(2));
+  }
+
+  const baseRoot = pathApi.resolve(String(currentRoot || process.cwd()).trim() || process.cwd());
+  return pathApi.resolve(baseRoot, candidate);
+}