chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Hyperlight.HyperlightSandbox.Guest.Python" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hyperlight\Microsoft.Agents.AI.Hyperlight.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="skills\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates a HarnessAgent with ALL features enabled, plus:
+// - Hyperlight CodeAct (HyperlightCodeActProvider) for sandboxed Python code execution
+// - Skills (AgentSkillsProvider) discovering a local "regex-tester" skill
+//
+// The agent can plan tasks with todos, manage modes, store memories, read/write files,
+// search the web, approve sensitive tools, discover and use skills, and execute arbitrary
+// Python code in a Hyperlight sandbox — all pre-configured by the HarnessAgent.
+//
+// Try asking: "Help me write a regex that matches valid email addresses, then test it."
+//
+// Special commands:
+//   /todos  — Display the current todo list without invoking the agent.
+//   /mode   — Get or set the current agent mode.
+//   /exit   — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Harness.Shared.Console;
+using HyperlightSandbox.Guest.Python;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hyperlight;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+const string TracingSourceName = "Harness.CodeExecution";
+
+// Set up OpenTelemetry tracing that writes spans to a text file.
+using var tracerProvider = HarnessTracing.CreateFileTracerProvider(TracingSourceName);
+
+// Create the HyperlightCodeActProvider with the Python/Wasm backend.
+// The guest module path is resolved automatically from the Hyperlight.HyperlightSandbox.Guest.Python NuGet package.
+using var codeAct = new HyperlightCodeActProvider(
+    HyperlightCodeActProviderOptions.CreateForWasm(PythonGuestModule.GetModulePath()));
+
+var instructions =
+    """
+    ## Technical Assistant Instructions
+
+    You are a code-powered technical assistant. You can execute Python code in a sandboxed environment
+    to solve problems precisely rather than guessing. You also have access to skills that provide
+    structured workflows for specific technical tasks.
+
+    ### Code Execution
+
+    When a problem requires computation, validation, or testing:
+    - Write Python code and use `execute_code` to run it in the sandbox.
+    - Always verify results by running the code rather than reasoning about what would happen.
+    - If code fails, read the error message carefully, fix the issue, and retry.
+
+    ### Skills
+
+    You have access to discoverable skills. When a task matches a skill's description:
+    - Follow the skill's instructions carefully.
+    - Use the skill's reference materials for context.
+    - Combine the skill's workflow with code execution when appropriate.
+
+    ### Planning and Research
+
+    For complex tasks:
+    - Break the problem into steps using your todo list.
+    - Research background information using web search when needed.
+    - Save important findings to file memory for later reference.
+
+    ### Presenting Results
+
+    - Show your work: include the code you ran and its output.
+    - Explain what each part of your solution does.
+    - If applicable, save final results to file memory.
+    """;
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+// Create the agent with ALL HarnessAgent features enabled plus Hyperlight CodeAct.
+// No Disable* flags are set — TodoProvider, AgentModeProvider, FileMemory, FileAccess,
+// ToolApproval, WebSearch, and AgentSkillsProvider are all active.
+AIAgent agent =
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        new AIProjectClientOptions { RetryPolicy = new ClientRetryPolicy(3) })
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(deploymentName)
+    .AsHarnessAgent(new HarnessAgentOptions
+    {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
+        Name = "CodeExecutionAgent",
+        Description = "A technical assistant with sandboxed code execution and skill-based workflows.",
+        OpenTelemetrySourceName = TracingSourceName,
+        // Point the file memory at a local folder for persistent memory across sessions.
+        FileMemoryStore = new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
+        // Add the HyperlightCodeActProvider so the agent can execute Python code in a sandbox.
+        AIContextProviders = [codeAct],
+        ChatOptions = new ChatOptions
+        {
+            Instructions = instructions,
+            MaxOutputTokens = MaxOutputTokens,
+            Reasoning = new() { Effort = ReasoningEffort.Medium },
+        },
+    });
+
+// Run the interactive console session using the shared HarnessConsole helper.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    userPrompt: "Ask me a technical question, or try: \"Help me write a regex that matches valid email addresses.\"",
+    new HarnessConsoleOptions
+    {
+        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
+            agent,
+            planModeName: "plan",
+            executionModeName: "execute",
+            maxContextWindowTokens: MaxContextWindowTokens,
+            maxOutputTokens: MaxOutputTokens),
+        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
+    });
@@ -0,0 +1,51 @@
+# Harness Step 04 — Code Execution (Hyperlight + Skills)
+
+This sample demonstrates a HarnessAgent with **all features enabled**, plus:
+
+- **Hyperlight CodeAct** — sandboxed Python code execution via `execute_code` (requires KVM)
+- **Skills** — file-based skill discovery (a `regex-tester` skill is included)
+
+The agent can plan tasks, manage modes, store memories, read/write files, search the web, approve sensitive operations, discover and use skills, and execute arbitrary Python code — all pre-configured by the HarnessAgent.
+
+## Prerequisites
+
+- .NET 10 SDK
+- An Azure AI Foundry project endpoint
+- KVM-capable host (the Hyperlight sandbox runs code in micro-VMs)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FOUNDRY_PROJECT_ENDPOINT` | Your Azure AI Foundry project endpoint |
+| `FOUNDRY_MODEL` | Model deployment name (default: `gpt-5.4`) |
+
+## Running
+
+```bash
+dotnet run
+```
+
+## What to Try
+
+- **Regex testing**: "Help me write a regex that matches valid email addresses, then test it against some examples."
+- **Code execution**: "Calculate the first 20 prime numbers using the Sieve of Eratosthenes."
+- **Skill + code combo**: "I need a regex for ISO 8601 dates — test it thoroughly with edge cases."
+
+## Included Skill
+
+The `skills/regex-tester/` skill instructs the agent to validate regex patterns by executing Python test code in the Hyperlight sandbox. It includes a regex cheatsheet as reference material.
+
+## Features Enabled
+
+| Feature | Description |
+|---------|-------------|
+| TodoProvider | Task planning and tracking (`/todos` command) |
+| AgentModeProvider | Mode switching (`/mode` command) |
+| FileMemoryProvider | Persistent memory stored as files |
+| FileAccessProvider | Read/write files in a working directory |
+| ToolApproval | Don't-ask-again approval for sensitive tools |
+| WebSearch | Built-in hosted web search |
+| AgentSkillsProvider | Discovers and uses skills from the `skills/` folder |
+| HyperlightCodeActProvider | Sandboxed Python execution via `execute_code` |
+| OpenTelemetry | Trace logging to a text file |
@@ -0,0 +1,36 @@
+---
+name: regex-tester
+description: Validate, test, and debug regular expressions by executing them against sample inputs. Use when asked to build, verify, or explain a regex pattern.
+---
+
+## Usage
+
+When the user asks you to create, validate, or debug a regular expression:
+
+1. **Understand the requirement** — clarify what the pattern should match and what it should reject.
+2. **Consult the cheatsheet** — review `references/regex-cheatsheet.md` for syntax reminders if needed.
+3. **Write and execute test code** — use the `execute_code` tool to run Python code that:
+   - Compiles the regex with `re.compile()`
+   - Tests it against a set of positive examples (should match) and negative examples (should not match)
+   - Extracts and displays any capturing groups
+   - Reports pass/fail for each test case
+4. **Iterate** — if any test fails, refine the pattern and re-run until all cases pass.
+5. **Present the result** — give the user the final pattern, explain what each part does, and show the test results.
+
+## Example Test Script
+
+```python
+import re
+
+pattern = re.compile(r'^[\w.+-]+@[\w-]+\.[\w.-]+$')
+
+positives = ["user@example.com", "first.last+tag@sub.domain.org"]
+negatives = ["@missing.com", "no-at-sign", "spaces in@address.com"]
+
+for s in positives:
+    assert pattern.match(s), f"FAIL: expected match for '{s}'"
+for s in negatives:
+    assert not pattern.match(s), f"FAIL: expected no match for '{s}'"
+
+print("All tests passed!")
+```
@@ -0,0 +1,97 @@
+# Regex Quick Reference (Python `re` module)
+
+## Character Classes
+
+| Pattern | Matches |
+|---------|---------|
+| `.`     | Any character except newline |
+| `\d`    | Digit `[0-9]` |
+| `\D`    | Non-digit |
+| `\w`    | Word character `[a-zA-Z0-9_]` |
+| `\W`    | Non-word character |
+| `\s`    | Whitespace `[ \t\n\r\f\v]` |
+| `\S`    | Non-whitespace |
+| `[abc]` | Any of a, b, or c |
+| `[^abc]`| Any character except a, b, c |
+| `[a-z]` | Range: a through z |
+
+## Quantifiers
+
+| Pattern | Meaning |
+|---------|---------|
+| `*`     | 0 or more (greedy) |
+| `+`     | 1 or more (greedy) |
+| `?`     | 0 or 1 (greedy) |
+| `{n}`   | Exactly n |
+| `{n,}`  | n or more |
+| `{n,m}` | Between n and m |
+| `*?`, `+?`, `??` | Non-greedy versions |
+
+## Anchors
+
+| Pattern | Meaning |
+|---------|---------|
+| `^`     | Start of string (or line with `re.MULTILINE`) |
+| `$`     | End of string (or line with `re.MULTILINE`) |
+| `\b`    | Word boundary |
+| `\B`    | Non-word boundary |
+
+## Groups and Backreferences
+
+| Pattern | Meaning |
+|---------|---------|
+| `(...)` | Capturing group |
+| `(?:...)`| Non-capturing group |
+| `(?P<name>...)` | Named group |
+| `\1`    | Backreference to group 1 |
+| `(?=...)` | Positive lookahead |
+| `(?!...)` | Negative lookahead |
+| `(?<=...)` | Positive lookbehind |
+| `(?<!...)` | Negative lookbehind |
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `re.IGNORECASE` / `re.I` | Case-insensitive matching |
+| `re.MULTILINE` / `re.M`  | `^`/`$` match line boundaries |
+| `re.DOTALL` / `re.S`     | `.` matches newline |
+| `re.VERBOSE` / `re.X`    | Allow comments and whitespace |
+
+## Common Patterns
+
+| Use Case | Pattern |
+|----------|---------|
+| Email (simple) | `^[\w.+-]+@[\w-]+\.[\w.-]+$` |
+| IPv4 address | `^\d{1,3}(\.\d{1,3}){3}$` |
+| ISO date | `^\d{4}-\d{2}-\d{2}$` |
+| URL (http/https) | `^https?://[^\s/$.?#].[^\s]*$` |
+| Phone (US) | `^(\+1)?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}$` |
+
+## Python API
+
+```python
+import re
+
+# Test if a string matches
+re.match(r'pattern', "string")       # match at start
+re.search(r'pattern', "string")      # match anywhere
+re.fullmatch(r'pattern', "string")   # match entire string
+
+# Find all matches
+re.findall(r'\d+', "abc 123 def 456")  # ['123', '456']
+
+# Named groups
+m = re.match(r'(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})', "2025-01-15")
+m.group('year')   # '2025'
+
+# Replace
+re.sub(r'\d+', 'X', "abc 123 def")   # 'abc X def'
+
+# Split
+re.split(r',+', "a,b,,c")            # ['a', 'b', 'c']
+
+# Compile for reuse
+pattern = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+pattern.match("2025-01-15")           # Match object
+```