OpenCode: tutorial completo, dall'installazione a un gateway .NET Minimal API

# repository GitHub (ex sst/opencode, oggi sotto l'org anomalyco)
https://github.com/anomalyco/opencode

# sito e documentazione
https://opencode.ai/docs

# script ufficiale (macOS / Linux / WSL)
curl -fsSL https://opencode.ai/install | bash

# in alternativa: npm
npm install -g opencode-ai

# oppure Homebrew (tap consigliato dal team)
brew install anomalyco/tap/opencode

# verifica
opencode --version

opencode

# dentro la TUI:
/connect   # → Anthropic → Manually enter API Key
/connect   # → GitHub Copilot → device flow

# modelli realmente disponibili per gli account collegati
/models

opencode

# dentro la TUI:
/connect
# → OpenAI
# → ChatGPT Plus/Pro oppure Manually enter API Key

/models

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (locale)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3.5:4b": {
          "name": "Qwen3.5 4B",
          "limit": { "context": 32768, "output": 8192 }
        },
        "qwen3.5:9b": {
          "name": "Qwen3.5 9B",
          "limit": { "context": 32768, "output": 8192 }
        }
      }
    }
  },

  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "ollama/qwen3.5:4b",

  "agent": {
    "build":   { "model": "anthropic/claude-sonnet-4-6" },
    "plan":    { "model": "openai/gpt-5.2-codex" },
    "explore": { "model": "ollama/qwen3.5:9b" },
    "general": { "model": "github-copilot/gpt-5.2" }
  }
}

# small_model leggero (~3,4 GB)
ollama pull qwen3.5:4b

# modello locale per explore (~6,6 GB)
ollama pull qwen3.5:9b

# budget runtime usato anche in opencode.json
export OLLAMA_CONTEXT_LENGTH=32768

# macOS app: imposta la variabile e riavvia Ollama
launchctl setenv OLLAMA_CONTEXT_LENGTH 32768

---
description: Review del diff per bug, test mancanti e style drift
mode: subagent
model: github-copilot/gpt-5.2
temperature: 0.2
permission:
  edit: deny
  bash: ask
---
Sei un code reviewer. Restituisci una punch list per severità:
must-fix, should-fix, nice-to-have.

# avvio il server headless (nella cartella del progetto su cui deve lavorare)
OPENCODE_SERVER_PASSWORD=segretissimo opencode serve --port 4096

# 1) creo una sessione
curl -s -u opencode:segretissimo -X POST http://127.0.0.1:4096/session \
  -H 'Content-Type: application/json' -d '{"title":"demo"}'
# → {"id":"ses_090d852eeffeul0zvfzfR2HT77", ...}

# 2) mando un prompt alla sessione (sincrono: aspetta la risposta)
curl -s -u opencode:segretissimo -X POST \
  http://127.0.0.1:4096/session/ses_090d852eeffeul0zvfzfR2HT77/message \
  -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"Spiegami questo repository"}]}'

dotnet new web -f net9.0 -n OpenCodeGateway && cd OpenCodeGateway
dotnet add package Refit.HttpClientFactory --version 13.1.0
dotnet add package Microsoft.AspNetCore.OpenApi --version 9.0.17
dotnet user-secrets init
dotnet user-secrets set "OpenCode:Password" "segretissimo"
dotnet user-secrets set "Gateway:ApiKey" "genera-un-valore-lungo-e-casuale"

# struttura finale
# OpenCodeGateway/
# ├── Program.cs
# ├── appsettings.json
# ├── Settings/OpenCodeSettings.cs
# ├── Models/Models.cs
# ├── Clients/IOpenCodeApi.cs
# ├── Services/AssistantService.cs + GatewayExceptions.cs
# ├── Security/GatewayApiKeyFilter.cs
# ├── Extensions/ServiceCollectionExtensions.cs
# └── Endpoints/AssistantEndpoints.cs

public sealed class OpenCodeSettings
{
    public const string SectionName = "OpenCode";

    public string BaseUrl { get; init; } = "http://127.0.0.1:4096";
    public string Username { get; init; } = "opencode";
    public string Password { get; init; } = string.Empty;
    public int TimeoutSeconds { get; init; } = 300;
}

public sealed class GatewaySettings
{
    public const string SectionName = "Gateway";
    public string ApiKey { get; init; } = string.Empty;
    public string[] AllowedAgents { get; init; } = ["build", "plan", "explore", "general"];
}

// ----- contratti del gateway -----
public record AskRequest(string Prompt, string? Agent = null, string? SessionId = null);
public record AskResponse(string SessionId, string Reply);
public record ApiErrorResponse(string Code, string Error);

// ----- contratti del server OpenCode (camelCase sul filo) -----
public record CreateSessionRequest(string? Title = null);
public record OpenCodeSession(string Id, string? Title = null);

public record OpenCodeMessagePart(string Type, string Text);
public record SendMessageRequest(IReadOnlyList<OpenCodeMessagePart> Parts, string? Agent = null);

public record OpenCodePart(string Type, string? Text = null);
public record OpenCodeMessageInfo(string Id, string Role);
public record OpenCodeMessageResponse(OpenCodeMessageInfo Info, IReadOnlyList<OpenCodePart> Parts);

using Refit;

public interface IOpenCodeApi
{
    [Post("/session")]
    Task<OpenCodeSession> CreateSessionAsync(
        [Body] CreateSessionRequest request, CancellationToken ct = default);

    [Post("/session/{sessionId}/message")]
    Task<OpenCodeMessageResponse> SendMessageAsync(
        string sessionId, [Body] SendMessageRequest request, CancellationToken ct = default);
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.Options;
using Refit;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddOpenCode(
        this IServiceCollection services, IConfiguration configuration)
    {
        services.AddOptions<OpenCodeSettings>()
            .Bind(configuration.GetSection(OpenCodeSettings.SectionName))
            .Validate(s => Uri.TryCreate(s.BaseUrl, UriKind.Absolute, out _),
                "OpenCode:BaseUrl must be an absolute URL")
            .Validate(s => !string.IsNullOrWhiteSpace(s.Password),
                "OpenCode:Password is required")
            .Validate(s => s.TimeoutSeconds is > 0 and <= 900,
                "OpenCode:TimeoutSeconds must be between 1 and 900")
            .ValidateOnStart();

        services.AddOptions<GatewaySettings>()
            .Bind(configuration.GetSection(GatewaySettings.SectionName))
            .Validate(s => !string.IsNullOrWhiteSpace(s.ApiKey),
                "Gateway:ApiKey is required")
            .Validate(s => s.AllowedAgents.Length > 0,
                "Gateway:AllowedAgents cannot be empty")
            .ValidateOnStart();

        var serializerOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web)
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        };

        services
            .AddRefitClient<IOpenCodeApi>(
                new RefitSettings(new SystemTextJsonContentSerializer(serializerOptions)))
            .ConfigureHttpClient((provider, client) =>
            {
                var settings = provider.GetRequiredService<IOptions<OpenCodeSettings>>().Value;
                client.BaseAddress = new Uri(settings.BaseUrl);
                client.Timeout = TimeSpan.FromSeconds(settings.TimeoutSeconds);
                var credentials = Convert.ToBase64String(
                    Encoding.UTF8.GetBytes($"{settings.Username}:{settings.Password}"));
                client.DefaultRequestHeaders.Authorization =
                    new AuthenticationHeaderValue("Basic", credentials);
            });

        services.AddScoped<IAssistantService, AssistantService>();
        return services;
    }
}

using System.Net;
using Refit;

public interface IAssistantService
{
    Task<AskResponse> AskAsync(AskRequest request, CancellationToken ct);
}

public sealed class AssistantService(
    IOpenCodeApi openCode,
    ILogger<AssistantService> logger) : IAssistantService
{
    public async Task<AskResponse> AskAsync(AskRequest request, CancellationToken ct)
    {
        try
        {
            var sessionId = request.SessionId
                ?? (await openCode.CreateSessionAsync(
                    new CreateSessionRequest("gateway"), ct)).Id;

            var message = new SendMessageRequest(
                [new OpenCodeMessagePart("text", request.Prompt)],
                request.Agent);

            var response = await openCode.SendMessageAsync(sessionId, message, ct);
            var reply = string.Join("\n", response.Parts
                .Where(p => p.Type == "text" && !string.IsNullOrWhiteSpace(p.Text))
                .Select(p => p.Text));
            return new AskResponse(sessionId, reply);
        }
        catch (ApiException ex) when (request.SessionId is not null &&
            ex.StatusCode == HttpStatusCode.NotFound)
        {
            throw new SessionNotFoundException(ex);
        }
        catch (ApiException ex)
        {
            logger.LogWarning(ex, "OpenCode returned HTTP {StatusCode}", (int)ex.StatusCode);
            throw new OpenCodeRejectedException(ex);
        }
        catch (ApiRequestException ex) when (ex.InnerException is TaskCanceledException &&
            !ct.IsCancellationRequested)
        {
            // Refit 13 wraps the HttpClient timeout: inner TaskCanceledException
            throw new OpenCodeTimeoutException(ex);
        }
        catch (ApiRequestException ex)
        {
            // Refit 13 wraps connection failures (server down, DNS, refused)
            throw new OpenCodeUnavailableException(ex);
        }
        catch (TaskCanceledException ex) when (!ct.IsCancellationRequested)
        {
            throw new OpenCodeTimeoutException(ex);
        }
    }
}

// Services/GatewayExceptions.cs
public sealed class SessionNotFoundException(Exception inner) : Exception("Session not found", inner);
public sealed class OpenCodeTimeoutException(Exception inner) : Exception("OpenCode timeout", inner);
public sealed class OpenCodeUnavailableException(Exception inner) : Exception("OpenCode unavailable", inner);
public sealed class OpenCodeRejectedException(Exception inner) : Exception("OpenCode rejected request", inner);

using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.Extensions.Options;

public sealed class GatewayApiKeyFilter(IOptions<GatewaySettings> options) : IEndpointFilter
{
    public const string HeaderName = "X-API-Key";

    public ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var supplied = context.HttpContext.Request.Headers[HeaderName].ToString();
        var suppliedHash = SHA256.HashData(Encoding.UTF8.GetBytes(supplied));
        var expectedHash = SHA256.HashData(Encoding.UTF8.GetBytes(options.Value.ApiKey));
        if (!CryptographicOperations.FixedTimeEquals(suppliedHash, expectedHash))
            return ValueTask.FromResult<object?>(TypedResults.Unauthorized());
        return next(context);
    }
}

// Endpoints/AssistantEndpoints.cs
public static class AssistantEndpoints
{
    public static void MapAssistantEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v1/assistant")
            .WithTags("Assistant")
            .AddEndpointFilter<GatewayApiKeyFilter>();

        group.MapPost("/", AskAsync).WithName("AskAssistant")
            .Produces(StatusCodes.Status401Unauthorized)
            .ProducesProblem(StatusCodes.Status502BadGateway)
            .ProducesProblem(StatusCodes.Status503ServiceUnavailable)
            .ProducesProblem(StatusCodes.Status504GatewayTimeout);
    }

    private static async Task<Results<Ok<AskResponse>, BadRequest<ApiErrorResponse>,
        NotFound<ApiErrorResponse>, ProblemHttpResult>> AskAsync(
        AskRequest request, IAssistantService assistant,
        IOptions<GatewaySettings> gateway, CancellationToken ct)
    {
        if (string.IsNullOrWhiteSpace(request.Prompt))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_prompt", "Prompt is required"));
        if (request.SessionId is not null &&
            !request.SessionId.StartsWith("ses_", StringComparison.Ordinal))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_session", "SessionId must start with 'ses_'"));
        if (request.Agent is not null &&
            !gateway.Value.AllowedAgents.Contains(request.Agent, StringComparer.Ordinal))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_agent", "Agent is not allowed"));

        try { return TypedResults.Ok(await assistant.AskAsync(request, ct)); }
        catch (SessionNotFoundException) { return TypedResults.NotFound(
            new ApiErrorResponse("session_not_found", "OpenCode session not found")); }
        catch (OpenCodeTimeoutException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status504GatewayTimeout, title: "OpenCode timed out"); }
        catch (OpenCodeUnavailableException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status503ServiceUnavailable, title: "OpenCode is unavailable"); }
        catch (OpenCodeRejectedException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status502BadGateway, title: "OpenCode rejected the request"); }
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddOpenCode(builder.Configuration);

var app = builder.Build();

app.MapOpenApi(); // GET /openapi/v1.json
app.MapAssistantEndpoints();

app.Run();

/* appsettings.json:
{
  "OpenCode": {
    "BaseUrl": "http://127.0.0.1:4096",
    "Username": "opencode",
    "TimeoutSeconds": 300
  },
  "Gateway": {
    "AllowedAgents": ["build", "plan", "explore", "general"]
  }
} */

# terminale 1 — il server OpenCode
OPENCODE_SERVER_PASSWORD=segretissimo opencode serve --port 4096

# terminale 2 — il gateway .NET
dotnet run --urls http://localhost:5099

# terminale 3 — la prova
curl -s -X POST http://localhost:5099/api/v1/assistant \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: genera-un-valore-lungo-e-casuale' \
  -d '{"prompt":"Say hello","agent":"plan"}'

# forma della risposta; testo e ID dipendono dall'esecuzione live
# → {"sessionId":"ses_...","reply":"..."}
# rimanda sessionId nel body per continuare la stessa conversazione

# CLAUDE.md — OpenCodeGateway

Gateway .NET 9 Minimal API che invoca OpenCode via `opencode serve`.

## Stack
- .NET 9 Minimal API — MAI Controller MVC
- Refit per i client HTTP — MAI HttpClient a mano
- DTO: record posizionali — MAI object/dynamic/tipi anonimi
- Settings: Options pattern con costante SectionName

## Comandi
- `dotnet build` — build
- `dotnet run --urls http://localhost:5099` — avvio sulla porta del tutorial

## Convenzioni
- Endpoint in `Endpoints/*.cs` come extension `MapXEndpoints` su MapGroup
- Registrazioni DI in `Extensions/ServiceCollectionExtensions.cs` (AddX)
- Handler: TypedResults + tipo di ritorno esplicito Results<...>

---
name: opencode-contract-check
description: Verifica i DTO Refit del gateway (Models/Models.cs)
  contro la spec OpenAPI live di opencode serve. Usare dopo un
  upgrade di OpenCode o quando CreateSession/SendMessage falliscono
  in deserializzazione.
---

# Check del contract drift verso opencode serve

1. Health check (basic auth se il server ha la password):
   `curl -s -u opencode:$OPENCODE_SERVER_PASSWORD http://127.0.0.1:4096/global/health`.
   Se il server è giù, chiedi di avviare `opencode serve` e fermati.
2. Scarica la spec OpenAPI 3.1 (JSON):
   `curl -s -u opencode:$OPENCODE_SERVER_PASSWORD http://127.0.0.1:4096/doc`.
3. Estrai gli schema dei soli endpoint che il gateway usa:
   `POST /session` e `POST /session/{id}/message`.
4. Confronta con i record in `Models/Models.cs`:
   OpenCodeSession, SendMessageRequest, OpenCodeMessageResponse,
   OpenCodePart (campi mancanti, rinominati, tipi cambiati).
5. Riporta il drift per severità (must-fix / nice-to-have) e proponi
   i diff sui record — NON applicarli senza conferma.
6. Annota nel report la versione del server letta da /global/health.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Refit;

// Contratto di esempio: sostituisco rotta e metodi con quelli dell'API reale.
public interface IProtectedApi
{
    [Get("/api/profile")]
    Task<HttpResponseMessage> GetProfileAsync(CancellationToken ct = default);
}

public static class ProtectedApiServiceCollectionExtensions
{
    public static IServiceCollection AddProtectedApi(this IServiceCollection services)
    {
        // I DelegatingHandler si registrano transient...
        services.AddTransient<JwtAuthHandler>();
        services.AddTransient<HttpLoggingHandler>();

        // ...e si agganciano al client Refit in catena.
        // In richiesta l'auth gira prima del logger; nessun header o body viene stampato.
        services
            .AddRefitClient<IProtectedApi>()
            .ConfigureHttpClient((provider, client) =>
            {
                var settings = provider.GetRequiredService<IOptions<AuthSettings>>().Value;
                client.BaseAddress = new Uri(settings.BaseUrl);
            })
            .AddHttpMessageHandler<JwtAuthHandler>()
            .AddHttpMessageHandler<HttpLoggingHandler>();

        return services;
    }
}

using System.Diagnostics;

public sealed class HttpLoggingHandler(ILogger<HttpLoggingHandler> logger) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        // Correla richiesta e risposta con un id corto.
        var id = Guid.NewGuid().ToString("N")[..8];
        var target = SafeTarget(request.RequestUri);
        var stopwatch = Stopwatch.StartNew();

        logger.LogInformation("[{Id} req] {Method} {Target}", id, request.Method, target);
        try
        {
            var response = await base.SendAsync(request, cancellationToken);
            logger.LogInformation(
                "[{Id} res] {StatusCode} in {ElapsedMs} ms",
                id, (int)response.StatusCode, stopwatch.ElapsedMilliseconds);
            return response;
        }
        catch (Exception exception)
        {
            logger.LogWarning(exception,
                "[{Id} err] {Method} {Target} after {ElapsedMs} ms",
                id, request.Method, target, stopwatch.ElapsedMilliseconds);
            throw;
        }
    }

    private static string SafeTarget(Uri? uri)
    {
        if (uri is null)
            return "(unknown)";

        var value = uri.IsAbsoluteUri ? uri.GetLeftPart(UriPartial.Path) : uri.OriginalString;
        var queryIndex = value.IndexOf('?');
        return queryIndex >= 0 ? value[..queryIndex] : value;
    }
}

using System.Net.Http.Headers;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Refit;

public sealed class AuthSettings
{
    public const string SectionName = "Auth";
    public string BaseUrl { get; init; } = string.Empty;
    public string UserName { get; init; } = string.Empty;
    public string Password { get; init; } = string.Empty;
}

public record TokenRequest(string UserName, string Password);
public record TokenResponse(string Token, DateTimeOffset ExpiresAt);

// Client Refit dell'endpoint che rilascia il JWT.
// Registrato SENZA JwtAuthHandler: niente auth ricorsiva.
public interface IAuthApi
{
    [Post("/api/auth/signin")]
    Task<TokenResponse> SignInAsync([Body] TokenRequest request, CancellationToken ct = default);
}

public sealed class JwtTokenProvider(
    IHttpClientFactory httpClientFactory,
    IOptions<AuthSettings> options)
{
    private readonly SemaphoreSlim gate = new(1, 1);
    private string? token;
    private DateTimeOffset expiresAt;

    /// <summary>Restituisce un JWT in cache, richiedendone uno nuovo se mancante o in scadenza.</summary>
    public async Task<string> GetTokenAsync(CancellationToken ct)
    {
        await gate.WaitAsync(ct);
        try
        {
            if (token is null || DateTimeOffset.UtcNow >= expiresAt.AddMinutes(-1))
            {
                var settings = options.Value;
                var authApi = RestService.For<IAuthApi>(httpClientFactory.CreateClient("AuthApi"));
                var response = await authApi.SignInAsync(new TokenRequest(settings.UserName, settings.Password), ct);
                token = response.Token;
                expiresAt = response.ExpiresAt;
            }

            return token;
        }
        finally
        {
            gate.Release();
        }
    }
}

public sealed class JwtAuthHandler(JwtTokenProvider tokenProvider) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        // Aggancia un bearer token valido a ogni chiamata in uscita.
        var token = await tokenProvider.GetTokenAsync(cancellationToken);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

        return await base.SendAsync(request, cancellationToken);
    }
}

public static class AuthServiceCollectionExtensions
{
    public static IServiceCollection AddJwtAuthentication(
        this IServiceCollection services, IConfiguration configuration)
    {
        services.AddOptions<AuthSettings>()
            .Bind(configuration.GetSection(AuthSettings.SectionName))
            .Validate(s => Uri.TryCreate(s.BaseUrl, UriKind.Absolute, out _),
                "Auth:BaseUrl must be an absolute URL")
            .Validate(s => !string.IsNullOrWhiteSpace(s.UserName),
                "Auth:UserName is required")
            .Validate(s => !string.IsNullOrWhiteSpace(s.Password),
                "Auth:Password is required")
            .ValidateOnStart();

        // Named client senza JwtAuthHandler: evita la ricorsione durante il login.
        services.AddHttpClient("AuthApi", (provider, client) =>
        {
            var settings = provider.GetRequiredService<IOptions<AuthSettings>>().Value;
            client.BaseAddress = new Uri(settings.BaseUrl);
        });

        services.AddSingleton<JwtTokenProvider>();
        services.AddTransient<JwtAuthHandler>();
        return services;
    }
}