wip

Author: KSemenenko

.github/workflows/ci.yml

@@ -26,13 +26,13 @@ jobs:
           dotnet-version: ${{ env.DOTNET_VERSION }}
 
       - name: Restore
-        run: dotnet restore CodexSharp.slnx
+        run: dotnet restore ManagedCode.CodexSharpSDK.slnx
 
       - name: Build
-        run: dotnet build CodexSharp.slnx -c Release -warnaserror --no-restore
+        run: dotnet build ManagedCode.CodexSharpSDK.slnx -c Release -warnaserror --no-restore
 
       - name: Test
-        run: dotnet test --solution CodexSharp.slnx -c Release --no-build
+        run: dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release --no-build
 
   aot-smoke:
     name: NativeAOT Smoke
@@ -49,7 +49,7 @@ jobs:
 
       - name: Publish AOT smoke app
         run: |
-          dotnet publish samples/CodexSharp.AotSmoke/CodexSharp.AotSmoke.csproj \
+          dotnet publish tests/AotSmoke/ManagedCode.CodexSharpSDK.AotSmoke.csproj \
             -c Release \
             -r linux-x64 \
             -p:PublishAot=true \

.github/workflows/codeql.yml

@@ -37,7 +37,7 @@ jobs:
           dotnet-version: '10.0.x'
 
       - name: Build
-        run: dotnet build CodexSharp.slnx -c Release -warnaserror
+        run: dotnet build ManagedCode.CodexSharpSDK.slnx -c Release -warnaserror
 
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@v3

.github/workflows/real-integration.yml

@@ -0,0 +1,52 @@
+name: Real Integration
+
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  DOTNET_VERSION: '10.0.x'
+  NODE_VERSION: '22'
+
+jobs:
+  codex-real-integration:
+    name: Real Codex Integration (${{ matrix.os }})
+    if: ${{ secrets.OPENAI_API_KEY != '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          submodules: recursive
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Install Codex CLI
+        run: npm install --no-save @openai/codex
+
+      - name: Restore
+        run: dotnet restore ManagedCode.CodexSharpSDK.slnx
+
+      - name: Run real integration tests
+        run: dotnet test --project tests/CodexSharpSDK.Tests.csproj -c Release -- --treenode-filter "/*/*/RealCodexIntegrationTests/*"
+        env:
+          CODEX_REAL_INTEGRATION: "1"
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CODEX_TEST_MODEL: gpt-5.3-codex

.github/workflows/release.yml

@@ -30,23 +30,35 @@ jobs:
       - name: Extract version
         id: version
         run: |
-          VERSION=$(grep -oPm1 "(?<=<Version>)[^<]+" Directory.Build.props)
+          VERSION=$(dotnet msbuild src/CodexSharpSDK.csproj -nologo -getProperty:Version)
+          if [ -z "$VERSION" ]; then
+            echo "Failed to resolve package version from project file."
+            exit 1
+          fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Version: $VERSION"
 
+      - name: Validate semantic version
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+            echo "Version '$VERSION' is not a valid semantic version."
+            exit 1
+          fi
+
       - name: Restore
-        run: dotnet restore CodexSharp.slnx
+        run: dotnet restore ManagedCode.CodexSharpSDK.slnx
 
       - name: Build
-        run: dotnet build CodexSharp.slnx -c Release -warnaserror --no-restore
+        run: dotnet build ManagedCode.CodexSharpSDK.slnx -c Release -warnaserror --no-restore
 
       - name: Test
-        run: dotnet test --solution CodexSharp.slnx -c Release --no-build
+        run: dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release --no-build
 
       - name: Pack
         run: |
           mkdir -p artifacts
-          dotnet pack src/CodexSharp/CodexSharp.csproj \
+          dotnet pack src/CodexSharpSDK.csproj \
             -c Release \
             --no-build \
             -o artifacts
@@ -145,30 +157,12 @@ jobs:
             git push origin "$TAG"
           fi
 
-      - name: Generate release notes
-        run: |
-          VERSION="${{ needs.publish.outputs.version }}"
-          {
-            echo "# ManagedCode.CodexSharp $VERSION"
-            echo
-            echo "Released on $(date +'%Y-%m-%d')"
-            echo
-            echo "## Packages"
-            for package in artifacts/*.nupkg; do
-              if [[ "$package" == *.snupkg ]]; then
-                continue
-              fi
-              name=$(basename "$package")
-              echo "- $name"
-            done
-          } > release_notes.md
-
       - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ needs.publish.outputs.version }}
           name: v${{ needs.publish.outputs.version }}
-          body_path: release_notes.md
+          generate_release_notes: true
           files: artifacts/*.*nupkg
           draft: false
           prerelease: false

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Project: ManagedCode.CodexSharp
+Project: ManagedCode.CodexSharpSDK
 Stack: .NET 10, C# 14, TUnit, GitHub Actions, NativeAOT, NuGet, Codex CLI integration
 
 Follows [MCAF](https://mcaf.managed-code.com/)
@@ -64,12 +64,12 @@ If no new rule is detected -> do not update the file.
 
 ### Commands
 
-- build: `dotnet build CodexSharp.slnx -c Release -warnaserror`
-- test: `dotnet test --solution CodexSharp.slnx -c Release`
-- format: `dotnet format CodexSharp.slnx`
-- analyze: `dotnet build CodexSharp.slnx -c Release -warnaserror /p:TreatWarningsAsErrors=true`
-- coverage: `dotnet test --solution CodexSharp.slnx -c Release -- --coverage --coverage-output-format cobertura --coverage-output coverage.cobertura.xml`
-- aot-smoke: `dotnet publish samples/CodexSharp.AotSmoke/CodexSharp.AotSmoke.csproj -c Release -r osx-arm64 /p:PublishAot=true`
+- build: `dotnet build ManagedCode.CodexSharpSDK.slnx -c Release -warnaserror`
+- test: `dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release`
+- format: `dotnet format ManagedCode.CodexSharpSDK.slnx`
+- analyze: `dotnet build ManagedCode.CodexSharpSDK.slnx -c Release -warnaserror /p:TreatWarningsAsErrors=true`
+- coverage: `dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release -- --coverage --coverage-output-format cobertura --coverage-output coverage.cobertura.xml`
+- aot-smoke: `dotnet publish tests/AotSmoke/ManagedCode.CodexSharpSDK.AotSmoke.csproj -c Release -r osx-arm64 /p:PublishAot=true`
 
 ### Task Delivery (ALL TASKS)
 
@@ -86,6 +86,8 @@ If no new rule is detected -> do not update the file.
   - `docs/ADR/*` for design/architecture decisions
   - `docs/Architecture/Overview.md` when module boundaries or interactions change
 - Implement code and tests together.
+- When asked to fix review findings, close every confirmed finding in the same pass; do not leave partial fixes.
+- Do not keep or add public sample projects; repository focus is SDK + tests (including AOT tests) only.
 - Run verification in this order:
   - focused tests for changed behavior
   - full solution tests
@@ -108,11 +110,20 @@ If no new rule is detected -> do not update the file.
 
 ### Testing (ALL TASKS)
 
-- Testing framework is TUnit (`tests/CodexSharp.Tests`).
+- Testing framework is TUnit (`tests`).
+- TUnit/MTP does not support `--filter`; for focused runs use `dotnet test ... -- --treenode-filter "<pattern>"`.
+- Always invoke runner options after `--` (for example `dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release -- --treenode-filter "<pattern>"`); if a focused filter runs zero tests, treat it as an invalid filter and correct it before reporting results.
+- In this repository, method-level `treenode-filter` patterns resolve at depth 3 (`/*/*/*/<TestMethodName>`). For integration subset runs use `dotnet test --solution ManagedCode.CodexSharpSDK.slnx -c Release -- --treenode-filter "/*/*/*/RunAsync_*_EndToEnd"` (matches current `CodexExecIntegrationTests`).
+- For reliable discovery when selecting focused tests, use the built test app directly: `tests/bin/Release/net10.0/ManagedCode.CodexSharpSDK.Tests --list-tests` (the `dotnet test ... -- --list-tests` wrapper can report zero tests in this setup).
 - Every behavior change must include or update tests.
 - Prefer behavior-level tests over trivial implementation tests.
-- For CLI process interactions, use `FakeCodexProcessRunner` test doubles rather than invoking external binaries.
+- Integration test sandboxes must be created under the repository `tests` tree (for example `tests/.sandbox/*`) for deterministic, inspectable paths; do not use `Path.GetTempPath()` for test sandbox directories.
+- For CLI process interaction tests, use the real installed `codex` CLI (no `FakeCodexProcessRunner` test doubles).
+- Treat `codex` CLI as a test prerequisite: ensure local/CI test setup installs `codex` before running CLI interaction tests; do not replace this with fakes.
+- Real Codex integration tests must work with existing Codex CLI login/session by default; `OPENAI_API_KEY` is optional and must not be a hard requirement.
+- Do not bypass integration tests on Windows with unconditional early returns; keep tests cross-platform for supported Codex CLI environments.
 - Parser changes require tests in `ThreadEventParserTests` for supported and invalid payloads.
+- Parser performance tests must use representative mixed payloads across supported event/item types and assert parsed output shape; avoid single-payload stopwatch loops that do not validate branch coverage.
 - Client/thread concurrency changes require explicit concurrent tests.
 - Never delete/skip tests to get green CI.
 
@@ -126,12 +137,29 @@ If no new rule is detected -> do not update the file.
 
 - Follow `.editorconfig` and analyzer rules.
 - Always build with `-warnaserror` so warnings fail the build.
+- Prefer idiomatic, readable C# with clear naming and straightforward control flow so code can be understood quickly during review and maintenance.
+- Use synchronization primitives only when there is a proven shared-state invariant; prefer simpler designs over ad-hoc locking for maintainable production code.
 - No magic literals: extract constants/enums/config values.
 - Protocol and CLI string tokens are mandatory constants: never inline literals in parsing, mapping, or switch branches.
 - In SDK model records, never inline protocol type literals in constructors (`ThreadItem(..., "...")`, `ThreadEvent("...")`); always reference protocol constants.
 - Do not expose a public SDK type named `Thread`; use `CodexThread` to avoid .NET type-name conflicts.
-- Keep public API and naming aligned with package/namespace `ManagedCode.CodexSharp`.
+- Keep public API and naming aligned with package/namespace `ManagedCode.CodexSharpSDK`.
+- Solution/workspace file naming must use `ManagedCode.CodexSharpSDK` prefix for consistency with package identity.
+- Keep package/version metadata centralized in `Directory.Build.props`; avoid duplicating version structure or release metadata blocks in individual `.csproj` files unless a project-specific override is required.
+- Never hardcode guessed Codex/OpenAI model names in tests, docs, or defaults; verify supported models and active default via Codex CLI first.
+- Before setting or changing any `Model` value, read available models and current default from the local `codex` CLI in the same environment/account and only then update code/tests/docs.
+- Model identifiers in code/tests must come from centralized constants or a shared resolver helper; do not inline model string literals repeatedly.
+- Image input API must support passing local image data as file path, `FileInfo`, and `Stream`.
+- Use `Microsoft.Extensions.Logging.ILogger` for SDK logging extension points; do not introduce custom logger interfaces or custom log-level enums.
+- In tests, prefer `Microsoft.Extensions.Logging.Abstractions.NullLogger` instead of custom fake logger implementations when log capture is not required.
 - Default to AOT/trimming-safe patterns (explicit JSON handling, avoid reflection-heavy designs).
+- Avoid ambiguous option names like `*Override` for primary settings; prefer explicit names (for example executable path / working directory) and keep compatibility aliases only when necessary.
+- README first examples must be beginner-friendly: avoid advanced/optional knobs (for example `CodexPathOverride`) in the very first snippet.
+- When a README snippet shows model tuning, include `ModelReasoningEffort` together with `Model`.
+- Public examples should build output schemas with typed `StructuredOutputSchema` models and map responses to typed DTOs for readability and maintainability.
+- Do not keep or add `JsonSchema` helper abstractions in SDK API/tests; use typed request/response DTO models instead of schema-builder utilities.
+- Do not handcraft JSON with `JsonValue`/`JsonNode` literals for structured outputs in API/tests/examples; define typed DTO models and map schema/fields from those models.
+- Keep consumer usage examples in `README.md`; do not introduce standalone sample projects.
 
 ### Critical (NEVER violate)
 
@@ -165,9 +193,17 @@ If no new rule is detected -> do not update the file.
 - Explicit, deterministic behavior
 - Full test coverage for new logic
 - Clear docs with diagrams and direct code links
+- Simple onboarding examples first, advanced configuration later.
 
 ### Dislikes
 
 - Magic strings in protocol parsing and CLI mappings
 - Hidden assumptions in CI/release pipelines
+- Unreadable, non-idiomatic C# that looks chaotic and hard to reason about
+- Unjustified `lock`/thread-synchronization complexity that obscures intent and increases maintenance risk
 - Template placeholders left in production repository docs
+- Raw nested `JsonObject`/`JsonArray` schema literals in user-facing examples.
+- Public sample projects in this repository; prefer tests (including AOT tests) instead.
+- Custom logging abstractions when `ILogger` already solves the integration use case.
+- Performance tests that exercise only one parser payload and do not cover supported parsing branches.
+- Example code scattered across standalone sample projects instead of `README.md`.

CodexSharp.slnx

@@ -2,13 +2,19 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <IsPackable>false</IsPackable>
-    <RootNamespace>ManagedCode.CodexSharp.Tests</RootNamespace>
-    <AssemblyName>ManagedCode.CodexSharp.Tests</AssemblyName>
+    <RootNamespace>ManagedCode.CodexSharpSDK.Tests</RootNamespace>
+    <AssemblyName>ManagedCode.CodexSharpSDK.Tests</AssemblyName>
     <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
     <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
     <NoWarn>$(NoWarn);CA1707</NoWarn>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="AotSmoke/**/*.cs" />
+    <EmbeddedResource Remove="AotSmoke/**" />
+    <None Remove="AotSmoke/**" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="TUnit" />
     <PackageReference Include="coverlet.collector">
@@ -18,6 +24,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="../../src/CodexSharp/CodexSharp.csproj" />
+    <ProjectReference Include="../src/CodexSharpSDK.csproj" />
   </ItemGroup>
 </Project>

…CodexSharp.Tests/CodexSharp.Tests.csproj …harpSDK.Tests/CodexSharpSDK.Tests.csprojtests/CodexSharp.Tests/CodexSharp.Tests.csproj renamed to CodexSharpSDK.Tests/CodexSharpSDK.Tests.csproj tests/CodexSharp.Tests/CodexSharp.Tests.csproj renamed to CodexSharpSDK.Tests/CodexSharpSDK.Tests.csproj

@@ -1,7 +1,10 @@
-namespace ManagedCode.CodexSharp.Tests;
+namespace ManagedCode.CodexSharpSDK.Tests;
 
 public class CodexExecIntegrationTests
 {
+    private const string SandboxRootDirectoryName = ".sandbox";
+    private const string SandboxDirectoryPrefix = "codexsharp-integration-";
+
     [Test]
     public async Task RunAsync_UsesDefaultProcessRunner_EndToEnd()
     {
@@ -26,7 +29,7 @@ public async Task RunAsync_UsesDefaultProcessRunner_EndToEnd()
 
             var thread = client.StartThread(new ThreadOptions
             {
-                Model = "gpt-5",
+                Model = "gpt-5.3-codex",
                 SandboxMode = SandboxMode.WorkspaceWrite,
             });
 
@@ -40,7 +43,7 @@ public async Task RunAsync_UsesDefaultProcessRunner_EndToEnd()
             await Assert.That(args).Contains("exec");
             await Assert.That(args).Contains("--experimental-json");
             await Assert.That(args).Contains("--model");
-            await Assert.That(args).Contains("gpt-5");
+            await Assert.That(args).Contains("gpt-5.3-codex");
             await Assert.That(args).Contains("--sandbox");
             await Assert.That(args).Contains("workspace-write");
 
@@ -126,7 +129,11 @@ public async Task RunAsync_PropagatesNonZeroExitCode_EndToEnd()
 
     private static string CreateSandboxDirectory()
     {
-        var directory = Path.Combine(Path.GetTempPath(), $"codexsharp-integration-{Guid.NewGuid():N}");
+        var testsDirectory = Environment.CurrentDirectory;
+        var sandboxRootDirectory = Path.Combine(testsDirectory, SandboxRootDirectoryName);
+        Directory.CreateDirectory(sandboxRootDirectory);
+
+        var directory = Path.Combine(sandboxRootDirectory, $"{SandboxDirectoryPrefix}{Guid.NewGuid():N}");
         Directory.CreateDirectory(directory);
         return directory;
     }