SDK: .NET SDK with P/Invoke wrapper

[itomek]

Overview

Implement a .NET SDK (Gaia.Native) that wraps the GAIA C API via P/Invoke, providing idiomatic C# types and async/await support.

Priority

P1

Dependencies

• Issue A (SDK: C API core — error codes, lifecycle, agent CRUD #429) — GaiaHandle, GaiaError, gaia_agent_create/destroy (can start writing wrapper after A)
• Issues B (SDK: C API process_query with cancellation #430), C (SDK: C API unified event callback system #431), D (SDK: C API tool registration and MCP management #432), E (SDK: C API version, ABI stability, and config #433) — needed for full test coverage

Scope

Project Structure

nuget/Gaia.Native/
├── GaiaAgent.cs           # IDisposable wrapper, async process_query
├── GaiaEventArgs.cs       # Event type + payload types
├── GaiaException.cs       # GaiaError → .NET exception
├── NativeMethods.cs       # P/Invoke declarations (internal)
├── Gaia.Native.csproj     # targets net8.0; NuGet metadata
└── tests/
    └── GaiaAgentTests.cs

Implementation

• GaiaAgent implements IDisposable; finalizer calls gaia_agent_destroy() as safety net
• ProcessQueryAsync(string query, CancellationToken ct) → maps CancellationToken to gaia_cancel()
• event EventHandler<GaiaEventArgs> OnEvent — raised from GaiaEventCallback marshaling
• P/Invoke error handling: copy gaia_last_error() string before throwing GaiaException

Tests (GaiaAgentTests.cs)

• Create GaiaAgent, drop all references without Dispose(), force GC → no crash (finalizer safety net)
• ProcessQueryAsync with CancellationToken.Cancel() → OperationCanceledException
• GaiaException message matches gaia_last_error() string

Acceptance Criteria

• GaiaAgent is IDisposable with finalizer safety net
• Async/await API via ProcessQueryAsync
• CancellationToken maps to gaia_cancel()
• P/Invoke error copies gaia_last_error() before throwing
• NuGet package builds (dotnet pack)
• Tests pass on Linux and Windows

Risk

R4 (Medium): ABI stability — PR1a (C API) must merge and stabilize before PR1b (.NET) starts integration testing.

Phase

Phase 1c — can start writing against capi.h after A; integration tests after B-E.

PR

PR1b (separate from C++ PR1a; different review domain).

Related

• Depends on Issues A-E
• Part of M11: Multi-Language SDK