Program.cs

using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Collections.Concurrent;
using System.Reflection;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration.Json;
using Microsoft.Extensions.FileProviders;
using AIOrchestrator;
using UISupportGeneric;
using AgentBridge.Resources;
using Terminal.Gui.Input;

// First-run visibility: from the process start to the TUI drawing the console shows
// nothing — the single-file runtime extracts its embedded native libraries before Main
// runs, and in TUI mode Console output is nulled until the UI takes over. On slow
// machines that window can be long. Print a startup line immediately so the terminal
// is never silently black; the TUI clears the console when it draws.
Console.WriteLine($"AgentBridge {Assembly.GetExecutingAssembly().GetName().Version} starting — loading components, please wait...");

// The TUI nulls Console.Out/Error while it owns the screen (see the useTui block
// below). Capture the real writers now so the crash handler can restore them and
// still print a readable report when the process dies mid-TUI.
var realStandardOutput = Console.Out;
var realStandardError = Console.Error;
// Crash-safe console: when the process dies with an unhandled exception while the TUI
// owns the console, the screen is left black — and the AIOrchestrator crash handler
// below then sleeps 60 s before auto-restarting, so the user would stare at a black
// terminal the whole time (and again after a restart that crashes again). Registered
// FIRST so this handler restores a readable console and prints the error immediately;
// the AIOrchestrator handler still logs the crash to file and restarts afterwards.
AppDomain.CurrentDomain.UnhandledException += (_, e) =>
{
    // Restore the real console writers first: in TUI mode Console.Out/Error are
    // TextWriter.Null, which would otherwise swallow both the alt-screen exit and
    // the crash report printed just below.
    try { Console.SetOut(realStandardOutput); } catch { }
    try { Console.SetError(realStandardError); } catch { }
    try { Console.ResetColor(); } catch { }
    if (!OperatingSystem.IsWindows())
    {
        // Leave Terminal.Gui's alternate screen buffer (ANSI), then clear the primary.
        try { Console.Out.Write("\u001b[0m\u001b[?1049l"); } catch { }
    }
    try { Console.Clear(); } catch { }
    Console.Error.WriteLine();
    Console.Error.WriteLine("AgentBridge crashed:");
    Console.Error.WriteLine(e.ExceptionObject is Exception ex ? ex.ToString() : e.ExceptionObject?.ToString());
    // Best-effort crash diagnostics to the project's GitHub issues — SANITIZED payload (only
    // the exception type + our stack frames, never messages/user data, see CrashReporter.cs).
    // Disable from the TUI (Settings → General → "Crash report" check box) or appsettings
    // CrashReport:Enabled.
    CrashReporter.Report(e.ExceptionObject as Exception);
};
AppDomain.CurrentDomain.UnhandledException += AIOrchestrator.Utility.UnhandledException; //it catches application errors in order to prepare a log of the events that cause the crash

// Logging is ON by default. The TUI Settings → General panel toggles AIOrchestrator.Log
// interactively, but a headless service (or a test harness) needs the same switch here on
// the command line — the log file lands in logs/<pid>.txt next to the executable.
AIOrchestrator.Log.IsEnabled = true;


// ═══════════════════════════════════════════════════════════════════════
//  AgentBridge — OpenAI-compatible HTTP server for AgentHarness
//
//  Architecture (see AIOrchestrator/docs-dev/ARCHITECTURE.md):
//    Standalone clients (e.g. Giraffe AI) → HTTP endpoints → AgentHarness
//    → LLM + agent tools. The server hosts the AIOrchestrator library (which is
//    not directly executable) and exposes its chat pipeline as standard
//    OpenAI-compatible REST endpoints, so any OpenAI SDK works unchanged.
//
//  Standard endpoints (OpenAI-compatible):
//    POST /v1/chat/completions   (Chat Completions, streaming SSE, sessions)
//    POST /v1/files              (multipart upload + server-side Markdown conversion)
//    GET  /v1/files              (list uploaded files)
//    GET  /v1/files/{id}         (retrieve converted content)
//    GET  /v1/files/{id}/content (retrieve raw bytes — OpenAI Files API)
//    DELETE /v1/files/{id}       (delete an uploaded file — OpenAI Files API)
//    GET  /v1/models             (agent sets + LLM providers with characteristics)
//    GET  /v1/models/{id}        (single model details)
//    POST /v1/audio/speech       (text → speech, Kokoro neural TTS, returns WAV)
//    POST /mcp                   (MCP JSON-RPC endpoint: initialize, tools/list, tools/call)
//    GET  /health
//
//  Proprietary extensions (documented, additive, ignored by strict OpenAI clients):
//    POST /v1/control            (pilot: switch the LLM in use, features, reset, set the default for new sessions)
//    GET  /v1/control            (session state + platform capabilities)
//    POST /v1/voice/listen       (one-shot server-mic speech recognition, Windows)
//    GET  /v1/audio/voices       (TTS voices available on this platform)
//
//  Sessions: chat requests may carry session_id (extension) to keep the
//  conversation history across requests; the pilot endpoint switches the LLM
//  provider on the fly with a context-window check (see docs/API.md).
//
//  File attachments follow the same server-side conversion rule as the Blazor
//  UI (never client-side): uploaded bytes are stored as FileAttachment and
//  converted to Markdown via AgentHarness.ConvertAttachmentToMarkdown
//  (AllToMarkdown for documents, Z.ai GLM-OCR for images).
// ═══════════════════════════════════════════════════════════════════════

// ─────────────────────────────────────────────────────────────────────
// Command-line help — print usage and exit before the server starts.
// Any appsettings.json key is already overridable from the command line
// (WebApplication.CreateBuilder wires the command-line config provider
// with precedence over appsettings.json), so the help documents the
// app-specific keys plus that general mechanism.
// ─────────────────────────────────────────────────────────────────────
if (args.Contains("-h") || args.Contains("--help") || args.Contains("/?"))
{
    Console.WriteLine("""
        AgentBridge — OpenAI-compatible HTTP server for AgentHarness

        Usage:
          dotnet run --project AgentBridge.csproj [-- <options>]

        Options (command line overrides appsettings.json; any key is overridable
        with --Key:SubKey <value>):
          --LLM:Provider <name>   Default LLM provider for NEW sessions. An explicit default
                                  marked in providers.json (TUI main settings → "Set default")
                                  wins over this key; without a mark this key applies, and the
                                  first configured provider is the fallback. The session-scoped
                                  llm_provider field / POST /v1/control never change this default.
          --LLM:Anonymize <bool>  Anonymize NameOrKey elements before sending to the LLM
                                  (true|false)
          --SkipIndexingOnStartup <bool>
                                  Skip the DocumentsPath index build/refresh + file watcher
                                  at startup (true|false) — use during debug/dev when no
                                  document searches are needed (large folders index for minutes)
          --DocumentsPath <path>  Sandbox root for document indexing and file tools (default:
                                  the persisted rag_settings.json value, else the OS Documents
                                  folder). Validated and persisted like the TUI "Documents
                                  path" setting; a folder without an index is built once on
                                  first use (minutes on large trees)
          --no-update              Disable the automatic update check at startup (default on;
                                  use for services/CI that manage the binary themselves)
          --enable-log             Enable AIOrchestrator file logging (logs/&lt;pid&gt;.txt) — the TUI
                                  settings toggle works only interactively; headless runs need this
          --Voice:ExePath <path>  Path to AIOffice.VoiceAgent.Win.exe for POST /v1/voice/listen
                                  (default: <server dir>\voiceagent\AIOffice.VoiceAgent.Win.exe)
          --Urls <address>        Kestrel listening address, e.g. http://localhost:5290
          --environment <name>    ASP.NET environment: Development | Production

        Terminal UI (default when the console is interactive):
          Without flags the console opens the Qwen-Code-style terminal UI (chat,
          slash commands, model/tools/voice/TTS/files/help) while the server keeps
          answering API calls in the same process.
          --headless               Server only (no terminal UI) — for scripts/CI.
          --tui                    Force the terminal UI (falls back to server-only
                                   when the console is not interactive).

        Endpoints: /v1/chat/completions, /v1/files[/{id}[/content]], /v1/models[/{id}],
                   /v1/audio/speech, /v1/audio/voices, /v1/voice/listen, /v1/control, /mcp, /health

        Examples:
          dotnet run --project AgentBridge.csproj -- --LLM:Provider Zai
          dotnet run --project AgentBridge.csproj -- --LLM:Anonymize true
          dotnet run --project AgentBridge.csproj -- --SkipIndexingOnStartup true
          agent --headless         (server only, e.g. as a systemd service)
        """);
    return 0;
}

// ─────────────────────────────────────────────────────────────────────
// Auto-update updater mode: the temp extract of a newer release runs as its own
// process; it waits for this process to exit, swaps the files (the executable last,
// .old as rollback) and restarts with the original command line. Must run before
// the server is built — see AutoUpdate.cs / docs/autoupdate.md.
// ─────────────────────────────────────────────────────────────────────
if (args.Contains("--apply-update"))
    return AutoUpdate.RunUpdater(args);

// Remove leftovers of a previous update (rollback .old, stale temp area).
AutoUpdate.CleanupOnStartup();

// Single persistent-config layout (AppConfig): CWD anchored to the executable folder, legacy
// root config files (appsettings/providers/telegram/tools) migrated into PersistentData\,
// default appsettings seeded. In DEBUG, refuse to start when config json still sits next to
// the executable — the tripwire that keeps the layout rule from regressing (see the
// RELEASE-CHECKLIST before any push).
AppConfig.Initialize();
AppConfig.GuardNoStrayRootJson();

// LLM provider definitions (providers.json) obey the same rule: read/written under
// PersistentData\ for this host. The engine default (next to the exe) stays unchanged, so
// other hosts (AIOffice) keep their current layout. Seed the embedded factory copy so the
// file exists (and is hand-editable) from the first run.
ProviderConfigs.ConfigDirectory = AppConfig.PersistentDir;
ProviderConfigs.EnsureDefaultFile();

// ── Command line → configuration: neutralize the app's own bare switches ──
// --enable-log/--tui/--headless/--no-gui/--no-update carry no value, but the .NET command-line
// configuration provider pairs EVERY "--key" with the NEXT token as its value: left as they are a
// bare switch swallows the key that follows it, so with the documented start line
//
//     agent --headless --LLM:Anonymize true
//
// the configuration got `headless = "--LLM:Anonymize"` and the override was silently ignored
// (same for --Urls, --Sip:ListenPort, --Tts:Engine, any --Key:Sub after a bare switch), while the
// same values as environment variables worked. The switches themselves are read from args
// directly (see the flag checks below), so for the configuration they only need neutralizing:
// an explicit "=true" keeps the pairing exact. Regression test: e2e/CliFlags.
string[] bareSwitches = { "--headless", "--no-gui", "--tui", "--no-update", "--enable-log" };
var configArgs = args
    .Select(a => bareSwitches.Contains(a, StringComparer.OrdinalIgnoreCase) ? a + "=true" : a)
    .ToArray();

// Content root = the executable's folder (not the CWD): the standalone exe must find its
// content even when launched from another directory (double click, services, tests).
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = configArgs,
    ContentRootPath = AppContext.BaseDirectory
});

// appsettings.json is user-editable config and lives under PersistentData\ (AppConfig): the
// configuration chain is re-pointed at it WITHOUT changing precedence — the source is inserted
// first, so environment variables and the command line still override it (as when the file sat
// at the content root). The Web SDK's own content-root appsettings providers stay in the chain
// but find nothing, because no appsettings.json is shipped next to the exe anymore.
// AppConfig has already resolved a writable PersistentData (falling back to the OS app-data
// folder when the install dir is read-only); the Directory.Exists guard is defense-in-depth so a
// still-missing folder (both locations unwritable) boots with defaults instead of throwing —
// the PhysicalFileProvider constructor throws DirectoryNotFoundException on a missing folder.
// Regression: crash report #83.
if (Directory.Exists(AppConfig.PersistentDir))
{
    builder.Configuration.Sources.Insert(0, new JsonConfigurationSource
    {
        FileProvider = new PhysicalFileProvider(AppConfig.PersistentDir),
        Path = "appsettings.json",
        Optional = true,
        ReloadOnChange = false
    });
}

// ── Port separation — DEBUG and RELEASE are designed to coexist on one machine ──
// The installed release keeps the documented default ports (Urls http://localhost:5290,
// Sip:ListenPort 5060). A DEBUG build shifts those DEFAULTS (Urls 5291, Sip 6071) so a dev
// instance never fights the running release for the same resource. The shift applies only
// when the effective value is still the release default — an explicit override (CLI
// --Urls / --Sip:ListenPort, ASPNETCORE_URLS, a hand-edited appsettings.json) always wins.
// Every consumer that derives its address from this configuration — the TUI attachment,
// the /OfficeManager web app, the Giraffe web-client endpoint — follows the instance that
// launched it automatically. Resource table: docs-dev/ARCHITECTURE.md "Release and DEBUG
// coexistence".
#if DEBUG
if (string.Equals(builder.Configuration["Urls"], "http://localhost:5290", StringComparison.OrdinalIgnoreCase))
    builder.Configuration["Urls"] = "http://localhost:5291";
if (builder.Configuration["Sip:ListenPort"] == "5060")
    builder.Configuration["Sip:ListenPort"] = "6071";
#endif

// The FreeCAD chat workbench reads AGENTBRIDGE_URL to locate the chat endpoint. In a
// DEBUG session, publish this instance's endpoint at User level so a manually-launched
// FreeCAD inherits it and the chat connects with no manual env setup. The release build
// clears it so the chat falls back to its built-in http://localhost:5290 default.
#if DEBUG
Environment.SetEnvironmentVariable("AGENTBRIDGE_URL",
    (builder.Configuration["Urls"] ?? "http://localhost:5291").TrimEnd('/') + "/v1/chat/completions",
    EnvironmentVariableTarget.User);
#else
Environment.SetEnvironmentVariable("AGENTBRIDGE_URL", null, EnvironmentVariableTarget.User);
#endif

// The TUI (Tui.cs) is built on Terminal.Gui v2 — before changing anything about
// it, read docs-dev/TUI-DEVELOPMENT.md (local developer guide, offline reference).
// Terminal UI mode: by default the console opens the Qwen-Code-style TUI (chat +
// slash commands + voice/model/files/help) while the server keeps answering API
// calls in the same process — "CLI + API simultaneously". --headless restores the
// plain server console for scripts/CI; --tui forces the UI even when the console
// looks redirected. When the console is redirected (no interactive terminal) the
// UI is skipped automatically, so existing launchers keep working unchanged.
var forceTui = args.Contains("--tui");
var forceHeadless = args.Contains("--headless") || args.Contains("--no-gui");
var interactive = !Console.IsInputRedirected && !Console.IsOutputRedirected && !Console.IsErrorRedirected;
var useTui = forceTui || (!forceHeadless && interactive);

// Suppress library/console output when the TUI is active — SIPSorcery (SIP),
// WTelegramClient (Telegram), the AIOrchestrator engine (RagDocumentProcessor
// reindex warnings, the document-creation "FATAL" line) and other third-party
// libraries write directly to Console.Out AND Console.Error. Both streams share the
// same terminal, so a background write interleaves with Terminal.Gui's own output
// and corrupts the screen: stray error text and fragments of the previous reply
// appear in the empty area, the header and the footer, then vanish on the next
// redraw (issue #93). Silence both writers in Release; keep them in DEBUG so
// --headless and the test harnesses still see output.
if (useTui)
{
    bool keepConsoleOutput = Environment.GetCommandLineArgs().Any(a => a.Contains("DEBUG"));
    Console.SetOut(keepConsoleOutput ? realStandardOutput : TextWriter.Null);
    Console.SetError(keepConsoleOutput ? realStandardError : TextWriter.Null);
}

// The TUI needs a real console (cursor control, key input): forcing it on a
// redirected console would crash on the console APIs, so fall back to server-only.
if (forceTui && !interactive)
{
    Console.WriteLine("Console is not interactive — --tui ignored, starting server-only (--headless).");
    useTui = false;
}

// The terminal UI owns the console: suppress ASP.NET's console logging so it
// cannot garble the TUI (HTTP errors surface inside the UI itself).
if (useTui)
    builder.Logging.ClearProviders();

builder.Services.AddCors(o => o.AddDefaultPolicy(p =>
    p.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader()));

// Configure the default LLM provider for NEW sessions. Priority: the provider explicitly
// marked as default in providers.json (set from the TUI main-settings dialog "Set default",
// persisted) → the operator's appsettings "LLM:Provider" → the first configured provider.
// The session-scoped switches (/model, the llm_provider field / POST /v1/control) never
// touch this default — they change only the session currently in use (see docs/API.md
// "LLM switching").
var explicitDefault = ProviderConfigs.All.FirstOrDefault(p => p.IsDefault)?.ProviderName;
var startupProvider = !string.IsNullOrWhiteSpace(explicitDefault)
    ? explicitDefault
    : builder.Configuration["LLM:Provider"] ?? "";
if (string.IsNullOrWhiteSpace(startupProvider) || !ProviderConfigs.TryGet(startupProvider, out _))
{
    Console.WriteLine("LLM provider not configured — using the first configured provider.");
    startupProvider = ProviderConfigs.Default.ProviderName;
}

// Anonymization flag from appsettings "LLM:Anonymize" (default false). Overridable from the
// command line with --LLM:Anonymize true — the ASP.NET config chain already gives CLI
// precedence over appsettings.json, so a single Configuration read covers both sources.
var anonymize = builder.Configuration.GetValue<bool>("LLM:Anonymize");

// Startup indexing toggle from appsettings "SkipIndexingOnStartup" (default false, CLI
// --SkipIndexingOnStartup true). When true, the DocumentsPath index is neither built nor
// refreshed and the file watcher is not started: use during debug/dev when no document
// searches are needed, to skip the multi-minute full index on large folders. MUST be set
// before Setup.Load() below — Setup.RagDocumentProcessor is created lazily on first use,
// so this early assignment is what the processor sees (see Setup.SkipIndexingOnStartup).
// The CLI flag is read DIRECTLY from args (not only from the command-line configuration
// provider, which may not surface it): "--SkipIndexingOnStartup true" / "=true" / bare flag.
var skipIndexing = false;
for (int i = 0; i < args.Length; i++)
{
    if (!args[i].StartsWith("--SkipIndexingOnStartup", StringComparison.OrdinalIgnoreCase)) continue;
    if (args[i].Contains('='))
        bool.TryParse(args[i].Split('=', 2)[1], out skipIndexing);
    else if (i + 1 < args.Length && bool.TryParse(args[i + 1], out var v))
        skipIndexing = v;
    else
        skipIndexing = true;
    break;
}
Setup.SkipIndexingOnStartup = skipIndexing || builder.Configuration.GetValue<bool>("SkipIndexingOnStartup");

// Startup sandbox override from CLI/appsettings "DocumentsPath" (default: the persisted
// rag_settings.json value, else the OS Documents folder). Applied BEFORE the shared
// RagDocumentProcessor is created (see Setup.SkipIndexingOnStartup for the same contract):
// the processor is lazy, so this early assignment makes it start directly on the chosen
// root — no build of the previous default root is ever kicked off. Same CLI conventions as
// above: "--DocumentsPath <path>" or "--DocumentsPath=<path>" (quotes stripped, spaces kept).
var documentsPathOverride = (string?)null;
for (int i = 0; i < args.Length; i++)
{
    if (!args[i].StartsWith("--DocumentsPath", StringComparison.OrdinalIgnoreCase)) continue;
    if (args[i].Contains('='))
        documentsPathOverride = args[i].Split('=', 2)[1].Trim().Trim('"');
    else if (i + 1 < args.Length)
        documentsPathOverride = args[i + 1].Trim().Trim('"');
    break;
}
documentsPathOverride ??= builder.Configuration["DocumentsPath"];
if (!string.IsNullOrWhiteSpace(documentsPathOverride)
    && !Setup.TrySetDocumentsPathEarly(documentsPathOverride, out var documentsPathError))
{
    Console.WriteLine($"DocumentsPath override rejected: {documentsPathError}");
}

// This host has no settings UI of its own: load credentials persisted by the previous
// run (Setup.Save) from %LocalAppData%\{app}\setup.json — SMTP/IMAP for EMailTool.
// LLM API keys are NOT here: they live per-provider in providers.json (edited via the
// TUI /modelsetup provider dialog or directly — see docs/providers-config.md); the
// legacy key fields of setup.json are only a fallback when a provider has no key.
// Provider selection above stays appsettings-driven (Setup.Load only restores
// Setup.ProviderConfig if the file contains ProviderName). See Setup.Load XML docs.
// The assembly was renamed AgentBridge → agent: migrate the credentials file so the
// old %LocalAppData%\AgentBridge\setup.json still applies (Setup.SetupFilePath uses
// the entry-assembly name).
try
{
    var local = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
    var oldSetup = Path.Combine(local, "AgentBridge", "setup.json");
    var newSetup = Path.Combine(local, "agent", "setup.json");
    if (File.Exists(oldSetup) && !File.Exists(newSetup))
    {
        Directory.CreateDirectory(Path.GetDirectoryName(newSetup)!);
        File.Copy(oldSetup, newSetup);
        Console.WriteLine($"Migrated setup.json: {oldSetup} → {newSetup}");
    }
}
catch { /* best-effort migration */ }

Setup.Load();

// The task scheduler (TaskSchedulerTool) runs scheduled tasks as automated chats: it hands the
// host's default agent set to AgentHarness (same as a request without a model — presets +
// always-on core tools) and the configured startup provider (ProviderConfigs.Default alone is
// file-order, so leaving it null would pick the FIRST provider in providers.json instead).
AIOrchestrator.API.TaskSchedulerTool.SchedulerAgentToolNames = AgentTools.Resolve(null);
AIOrchestrator.API.TaskSchedulerTool.SchedulerProvider = startupProvider;

// Optional path to the VoiceAgent executable for POST /v1/voice/listen
// (appsettings "Voice:ExePath", CLI --Voice:ExePath). Null → server base directory.
VoiceBridge.ExePath = builder.Configuration["Voice:ExePath"];

// Preferred TTS engine (appsettings "Tts:Engine", CLI --Tts:Engine), exported to the
// plugins via PODCAST_TTS_ENGINE so they synthesize with the same engine as the host.
// The catalog lives in TtsEngineSupport (AIOrchestrator): kokoro is the only engine
// today — always available, in-process, model included in the archive. Future engines
// register there and get this selection path for free; a stale configured value falls
// back to the default and says why, so the TTS never breaks silently.
var ttsEngine = builder.Configuration["Tts:Engine"] ?? TtsEngineSupport.DefaultEngine;
if (!TtsEngineSupport.IsKnown(ttsEngine))
{
    Console.WriteLine($"TTS engine '{ttsEngine}' is unknown — using {TtsEngineSupport.DefaultEngine}.");
    ttsEngine = TtsEngineSupport.DefaultEngine;
}
else if (!TtsEngineSupport.IsAvailable(ttsEngine, out var ttsReason))
{
    Console.WriteLine($"TTS engine '{ttsEngine}' is not available on this machine ({ttsReason}) — using {TtsEngineSupport.DefaultEngine}.");
    ttsEngine = TtsEngineSupport.DefaultEngine;
}
Environment.SetEnvironmentVariable("PODCAST_TTS_ENGINE", ttsEngine);
Console.WriteLine($"TTS engine: {ttsEngine}");

var app = builder.Build();

// How long a session close waits for a chat that is still using it. An agent tool keeps
// running after the client cancelled its stream, and disposing the orchestrator under a live
// run would corrupt it — so a busy session is skipped rather than killed.
var sessionCloseTimeout = TimeSpan.FromSeconds(30);

// Every shutdown path (TUI exit, headless Ctrl+C, a stop request) funnels through the host
// lifetime: close the live sessions here so each conversation records its memory. The
// recording runs in AgentHarness.Dispose, so a session that is merely dropped when the
// process dies remembers nothing — an abrupt exit would silently lose the conversation.
// Best-effort and bounded (the process must still exit promptly); the TUI normally already
// closed everything before asking the app to stop, which makes this a no-op safety net.
app.Lifetime.ApplicationStopping.Register(() =>
{
    if (SessionStore.Count == 0) return;
    try
    {
        Log.LogStep($"Shutdown: recording the memory of {SessionStore.Count} live session(s)", monitor: true);
        var flush = Task.Run(() => SessionStore.CloseAllAsync(sessionCloseTimeout));
        if (!flush.Wait(TimeSpan.FromSeconds(120)))
            Log.LogStep("Shutdown memory recording timed out", monitor: true);
    }
    catch (Exception ex) { Log.LogStep($"Shutdown memory recording failed: {ex.Message}"); }
});

// Tool plugins (DocumentTool, SpreadsheetTool, OfficeTool): loaded DYNAMICALLY from the
// Tools/ folder next to the executable — no project depends on a plugin. The agent sets
// pass tool names and McpToolRegistry resolves them at runtime.
_ = AgentBridge.ToolPlugins.Host;

#if DEBUG
// Dev convenience: now that the plugin assemblies are loaded, drop the FreeCAD chat
// workbench into any installed FreeCAD Mod dir so opening the FreeCAD GUI shows the
// chat pointed at this debug instance (AGENTBRIDGE_URL above) without the agent having
// used FreeCADTool first. Reflection keeps the install logic single-sourced in the
// plugin; if the plugin is absent this is a no-op.
_ = System.Threading.Tasks.Task.Run(() =>
{
    try
    {
        var ft = AppDomain.CurrentDomain.GetAssemblies()
            .Select(a => a.GetType("AIOrchestrator.API.FreeCADTool", throwOnError: false))
            .FirstOrDefault(t => t != null);
        ft?.GetMethod("PreInstallChatMod", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static)
            ?.Invoke(null, null);
    }
    catch (Exception ex) { Log.LogStep($"FreeCAD chat pre-install skipped: {ex.Message}"); }
});
#endif

// OfficeManager hub: tracks every agent instance in this process (sessions of any medium,
// stateless API calls, subagents) and serves them to the /OfficeManager web app over the
// WebSocket protocol (see OfficeBridge.cs). Agents created by OTHER processes forward their
// lifecycle events here via AgentHarness.ForwardGlobalProgressTo → POST /v1/office/events.
OfficeBridge.Init(startupProvider, anonymize);

// Dynamic-hash conversation correlation for stateless clients without session_id (see
// StatelessConversation.cs): wires the transcript-hash cleanup on session removal.
StatelessConversation.Init();

// SIP telephony (auto-answer + PIN, outgoing calls — see docs/sip.md): initialized from the
// "Sip" appsettings section; the server itself starts right before the launch mode below so a
// bind failure (port in use) cannot kill the HTTP API — it is reported and logged only.
SipBridge.Init(app.Configuration, startupProvider, anonymize);

// Telegram chat medium (WTelegramClient userbot — see docs/telegram.md): initialized from
// telegram.json under PersistentData\ (never overwritten by updates).
// The bridge starts at boot only when Enabled=true; the login is fully automatic when the
// .session file already exists, otherwise the TUI drives the pending verification code.
TelegramBridge.Init(startupProvider, anonymize);

// Auto-update toggle: CLI --no-update > persisted state (TUI File → Auto-Update)
// > appsettings default. The persisted file lives in the OS app-data folder, so
// updates never touch it (see RELEASING.md, storage tiers).
if (!AutoUpdate.LoadState(args.Contains("--no-update")))
    AutoUpdate.Enabled = app.Configuration.GetValue<bool>("AutoUpdate:Enabled", true);

// Crash reporting toggle (TUI Settings → General → "Crash report" check box / /crashreport):
// persisted state in the OS
// app-data folder wins, else the appsettings default. Repo/token come from appsettings
// (CrashReport:Repo, CrashReport:Token — token optional; without it the report opens as a
// pre-filled GitHub issue the user reviews before submitting, see CrashReporter.cs).
if (!CrashReporter.LoadState())
    CrashReporter.Enabled = app.Configuration.GetValue("CrashReport:Enabled", true);
CrashReporter.Repo = app.Configuration["CrashReport:Repo"] ?? CrashReporter.Repo;
CrashReporter.Token = app.Configuration["CrashReport:Token"];

// Agent reporting toggle (TUI Settings → General → "Malfunction report" check box /
// /malfunctionreport): the agent
// opens malfunction reports and feature requests as GitHub issues through the SAME delivery
// pipeline (MalfunctionReporterTool → CrashReporter.SendIssue). Own persisted gate in the
// OS app-data folder, independent from CrashReport:Enabled; default ON.
AIOrchestrator.API.MalfunctionReporterTool.LoadState();

// Agent-tool errors (a tool method execution that threw and was surfaced to the agent) flow
// into the SAME GitHub-issue pipeline as critical errors: ToolErrorReporter (AIOrchestrator)
// subscribes to UISupportGeneric's method-execution events and reports through CrashReporter,
// honouring the CrashReport:Enabled toggle above (a new signature — tool method + exception
// HResult — is reported once). Host opt-in: only AgentBridge enables it.
ToolErrorReporter.Enable();

app.UseCors();

// ─────────────────────────────────────────────────────────────────────
// OfficeManager (web app) — static files + duplex WebSocket hub
//
// The 16-bit office app ships in the OfficeManager/ folder next to the
// executable (same csproj copy rule as docs/) and is served at
// /OfficeManager. The browser opens a WebSocket to /ws/office: the server
// streams agent lifecycle events (employees spawning at the door, tool
// methods, conversations) and receives chat prompts / close commands —
// see OfficeBridge.cs for the wire protocol. External hosts (AIOffice app,
// voice panels) forward their agents' events to POST /v1/office/events via
// AgentHarness.ForwardGlobalProgressTo, so every agent/subagent instance,
// however it was created, is reflected in the office.
// ─────────────────────────────────────────────────────────────────────
app.UseWebSockets(new WebSocketOptions { KeepAliveInterval = TimeSpan.FromSeconds(30) });

var officeDir = Path.Combine(AppContext.BaseDirectory, "OfficeManager");
var officeAvailable = Directory.Exists(officeDir);
if (officeAvailable)
{
    var officeFiles = new PhysicalFileProvider(officeDir);
    app.UseStaticFiles(new StaticFileOptions { FileProvider = officeFiles, RequestPath = "/OfficeManager" });
    // Routing treats the trailing slash as optional, so one pattern serves both /OfficeManager
    // and /OfficeManager/. The page uses ABSOLUTE asset URLs (/OfficeManager/...), so both work.
    var officeIndex = Path.Combine(officeDir, "index.html");
    app.MapGet("/OfficeManager", () => Results.File(officeIndex, "text/html"));
}
else
{
    Console.WriteLine("OfficeManager/ not found next to the executable — the web office is unavailable.");
}

// GET / — the browser landing page for the base address.
//
// AgentBridge is an API server, so before this the bare root (http://localhost:5290/)
// returned a bare 404. That confused anyone opening the base URL — most visibly the
// "Open the AI assistant" link on the AI-ERP login page, which points at the assistant's
// base address. This page turns that dead end into a useful entry point: it confirms the
// server is up and links to the browser UI (the AI office) and the API. It is fully
// self-contained (inline CSS, no external assets) so it renders with nothing else loaded.
app.MapGet("/", () =>
{
    var officeLink = officeAvailable
        ? "<a class=\"cta\" href=\"/OfficeManager\">Open the AI office &rarr;</a>"
        : "<p class=\"muted\">The web office is not installed next to the executable.</p>";
    var html = """
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>AgentBridge</title>
<style>
  :root { color-scheme: light dark; }
  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
         font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
         background: #0f1115; color: #e6e6e6; }
  .card { max-width: 34rem; padding: 2.5rem 2rem; text-align: center;
          background: #171a21; border: 1px solid #262b36; border-radius: 14px;
          box-shadow: 0 8px 30px rgba(0,0,0,.35); }
  h1 { margin: 0 0 .25rem; font-size: 1.6rem; }
  .ok { color: #5ad37a; font-weight: 600; }
  p { line-height: 1.5; }
  .muted { color: #9aa4b2; }
  .cta { display: inline-block; margin: 1.25rem 0; padding: .7rem 1.4rem;
         background: #3b82f6; color: #fff; text-decoration: none; border-radius: 8px; font-weight: 600; }
  .cta:hover { background: #2f6fd6; }
  .links { margin-top: 1rem; font-size: .9rem; }
  .links a { color: #7fb0ff; text-decoration: none; margin: 0 .5rem; }
  .links a:hover { text-decoration: underline; }
  code { background: #0b0d11; padding: .1rem .35rem; border-radius: 4px; }
</style>
</head>
<body>
  <div class="card">
    <h1>AgentBridge</h1>
    <p><span class="ok">&#10003; Running</span> &mdash; the AI assistant server is up.</p>
    __OFFICE__
    <p class="muted">This is the assistant's base address. Use the button above for the browser
    interface, or point a client at the OpenAI-compatible API.</p>
    <div class="links">
      <a href="/OfficeManager">AI office</a>
      <a href="/health">Health</a>
      <a href="/v1/models">API models</a>
    </div>
  </div>
</body>
</html>
""".Replace("__OFFICE__", officeLink);
    return Results.Content(html, "text/html; charset=utf-8");
});

app.Map("/ws/office", async (HttpContext context) =>
{
    if (context.WebSockets.IsWebSocketRequest)
    {
        using var ws = await context.WebSockets.AcceptWebSocketAsync();
        await OfficeBridge.HandleClientAsync(ws, context.RequestAborted);
    }
    else
    {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
    }
});

// Agents created by OTHER processes (AIOffice app, voice panels, schedulers) forward their
// GlobalProgress stream here — the same events AgentBridge raises for its own instances.
app.MapPost("/v1/office/events", (JsonElement body) =>
{
    if (body.ValueKind == JsonValueKind.Array)
        foreach (var item in body.EnumerateArray()) OfficeBridge.IngestExternalEvent(item);
    else
        OfficeBridge.IngestExternalEvent(body);
    return Results.Ok();
});

var jsonOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

// Agent-set ids exposed as "models" (each maps to a concrete tool set in
// ResolveAgentTypes). Derived from the AgentTools preset table plus the dynamic
// "all-files" preset, so the API surface and the TUI tool selection never drift apart.
var agentModelIds = AgentTools.AllIds;

// ─────────────────────────────────────────────────────────────────────
// POST /v1/chat/completions — OpenAI Chat Completions API
//
// Extensions over the OpenAI contract (all additive):
//   session_id    — keep the conversation history across requests (multi-turn).
//   llm_provider  — use a specific LLM provider for this request (default: appsettings).
// On session requests the response carries the session_id; switching the provider on
// a session is refused (409) when the accumulated history overflows the new provider's
// context window — the client resets the conversation via POST /v1/control first.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/chat/completions", async (
    HttpContext http,
    [FromBody] ChatCompletionRequest request,
    CancellationToken ct) =>
{
    try
    {
        var lastUserMessage = request.Messages?
            .LastOrDefault(m => m.Role == "user");
        if (lastUserMessage == null)
            return Results.BadRequest(new { error = "No user message found" });

        var prompt = ExtractTextContent(lastUserMessage.Content);
        if (string.IsNullOrWhiteSpace(prompt))
            return Results.BadRequest(new { error = "User message is empty" });

        var resolvedProvider = ResolveProvider(request.LlmProvider, startupProvider, out var providerError);
        if (providerError != null)
            return Results.BadRequest(new { error = providerError });
        var provider = resolvedProvider!;

        // Explicit tool list (additive extension, see ChatCompletionRequest.Tools) wins
        // over the agent set resolved from `model`. A filtered-empty list (whitespace or
        // unknown names only) falls back to the preset so the agent never runs with no
        // tools; unknown tool names are skipped by the tool registry.
        string[] agentToolNames;
        if (request.Tools is { Count: > 0 })
        {
            agentToolNames = request.Tools
                .Where(t => !string.IsNullOrWhiteSpace(t))
                .Select(t => t.Trim())
                .Distinct(StringComparer.OrdinalIgnoreCase)
                .ToArray();
            if (agentToolNames.Length == 0)
                agentToolNames = ResolveAgentTypes(request.Model);
        }
        else
        {
            agentToolNames = ResolveAgentTypes(request.Model);
        }
        var attachments = ResolveAttachments(request.FileIds);
        var maxIterations = request.MaxTokens > 0
            ? Math.Clamp(request.MaxTokens.Value / 100, 1, 200)
            : 200;

        ActiveSession? session = null;
        AgentHarness? owned = null;
        var sessionResumed = false;
        // The agent run, when this request started it on a worker task (the streaming path).
        // Declared out here so the finally can wait for it before releasing the gate and
        // disposing the harness — see the finally block.
        Task<(AgentResult Result, string Content, string FinishReason)>? run = null;
        try
        {
            if (!string.IsNullOrEmpty(request.SessionId))
            {
                session = SessionStore.Get(request.SessionId);
                if (session == null)
                {
                    // The session expired (idle timeout) or the server restarted: the client is
                    // still holding a dead id. Instead of failing with a 404 — which would leave it
                    // stuck on that id for every following prompt — the conversation CONTINUES on a
                    // new session. A client that resends its transcript (the OpenAI-style full
                    // `messages` array) gets the previous turns back via SeedHistory, the same
                    // continuation the stateless dynamic-hash path uses (StatelessConversation.cs);
                    // a client that resends only the newest message gets a fresh conversation. The
                    // new id travels back with the response (and in the SSE stream), so the client
                    // rebinds with no visible interruption.
                    if (HasAssistantHistory(request.Messages))
                    {
                        // The resent transcript is about to BECOME the new history, so the
                        // context-window guard is checked on it BEFORE the session exists: a refused
                        // continuation must not leave an orphan session behind (it would linger until
                        // the idle timeout, spawn an employee in OfficeManager and record a memory
                        // conversation at disposal, all for a run that never happened).
                        var seedEstimate = EstimateTokens(
                            string.Join("\n", SeedTurns(request.Messages).Select(t => t.Content)) + "\n" + prompt);
                        var seedFitError = ContextFitErrorFor(seedEstimate, provider);
                        if (seedFitError != null)
                            return Results.Json(seedFitError, statusCode: 409);

                        session = CreateSeededSession(request.Messages, provider);
                        sessionResumed = true;   // the previous turns really came back
                    }
                    else
                    {
                        session = SessionStore.Create(provider, anonymize);
                    }
                }

                // Switch the LLM in use on the fly (history preserved), but refuse when the
                // conversation overflows the target provider's context window.
                var target = session.Orchestrator.Provider;
                if (!string.Equals(target, provider, StringComparison.OrdinalIgnoreCase))
                    target = provider;
                var fitError = ContextFitError(session, target, prompt);
                if (fitError != null)
                    return Results.Json(fitError, statusCode: 409);
                if (!string.Equals(session.Orchestrator.Provider, provider, StringComparison.OrdinalIgnoreCase))
                    session.Orchestrator.SwitchProvider(provider);
            }
            else
            {
                // No session → the historical stateless behaviour (one orchestrator per request),
                // with one refinement: a third-party client that never sends session_id but RESENDS
                // the accumulated transcript is correlated back to its conversation via the dynamic
                // transcript hash (see StatelessConversation.cs), so its chat stays ONE session —
                // ONE persistent employee in OfficeManager — instead of a one-shot per message.
                // True one-shot requests (no prior assistant reply) keep the fresh-instance path.
                var contKey = StatelessConversation.ContinuationKey(request.Messages);
                var correlated = contKey != null ? StatelessConversation.Lookup(contKey) : null;
                if (correlated != null)
                {
                    // Known conversation → its session; pending transcript → start + seed it.
                    if (correlated.Length > 0)
                    {
                        session = SessionStore.Get(correlated);
                    }
                    else
                    {
                        session = CreateSeededSession(request.Messages, provider);
                        sessionResumed = true;   // the earlier turns really came back
                    }
                    if (session == null)
                        owned = new AgentHarness(provider, anonymize);
                }
                else if (HasAssistantHistory(request.Messages))
                {
                    // A multi-turn transcript we have never seen (server restart, or the first
                    // message was a true one-shot): start the conversation from the resent history.
                    session = CreateSeededSession(request.Messages, provider);
                    sessionResumed = true;       // the earlier turns really came back
                }
                else
                {
                    owned = new AgentHarness(provider, anonymize);
                }
            }

            // One chat at a time per conversation — both for the explicit session_id path and for
            // the correlated/seeded stateless path (the finally releases the gate).
            if (session != null)
                await session.Gate.WaitAsync(ct);

            // A settings edit of the provider in use (new key/endpoint/model, written to
            // providers.json) must reach this conversation now, not after a restart or a switch:
            // reload the pipeline from the current entry when it changed (no-op otherwise).
            session?.Orchestrator.ReloadProviderConfig();

            var orchestrator = session?.Orchestrator ?? owned!;
            // isLocalUser: the caller is at the desktop only when it reaches us from a loopback
            // address (same machine). Remote callers (including the SIP phone bridge) get false,
            // so OfficeTool's watch/desktop-only methods stay disabled for them.
            var isLocalUser = http.Connection.RemoteIpAddress != null
                && System.Net.IPAddress.IsLoopback(http.Connection.RemoteIpAddress);
            // Lean orchestrator: the agent keeps the system tools for immediate, simple work, and
            // the plugin tools ride behind a subagent. One entry point, so no chat path can miss
            // the split (see AgentTools.ExecuteSplit, AIOrchestrator docs → "Lean orchestrator").
            var sessionId = session?.Id;
            // The agent run can take a very long time — a podcast or a CAD build is tens of
            // minutes — so it runs on a worker task instead of on the request thread. A
            // streaming response needs it there: while the agent works, the connection would
            // otherwise carry ZERO bytes, and any client with a read timeout (or any proxy in
            // between) drops it long before the answer exists. The stream keeps it alive with
            // comments until the result is ready.
            run = Task.Run(() =>
            {
                var r = AgentTools.ExecuteSplit(orchestrator, prompt, agentToolNames,
                    maxIterations, attachments, isLocalUser);
                session?.AddTurnUsage(r.Usage);
                // Locale-neutral result codes (AgentResultCode) are rendered through the localized
                // dictionary in the current system language; LLM text (Message/Error) passes
                // through as-is. "No output generated" is also localized (Dictionary.NoOutputGenerated).
                var text = r.Message ?? AgentResultDisplay.ResultText(r) ?? Dictionary.NoOutputGenerated;
                // Keep the dynamic-hash correlation current (see StatelessConversation.cs): the
                // rolling transcript hash INCLUDING this reply is recorded under the
                // conversation, or marked pending when the request was a true one-shot — so the
                // next message that resends the transcript is routed back to the same conversation.
                if (request.Messages != null)
                {
                    var key = StatelessConversation.FullKey(request.Messages, text);
                    if (sessionId != null) StatelessConversation.Record(sessionId, key);
                    else StatelessConversation.MarkPending(key);
                }
                return (Result: r, Content: text, FinishReason: r.Success ? "stop" : "error");
            });

            if (request.Stream == true)
            {
                // The body is written HERE, inside the handler, instead of through Results.Stream.
                // Results.Stream runs its delegate only AFTER this handler returns, which would
                // let the finally below dispose the harness while the agent is still running on
                // the worker task (ObjectDisposedException inside SendQuery). Writing the body
                // in the handler's own lifetime keeps the whole turn — agent run, keepalives and
                // chunks — inside the scope that owns the harness.
                http.Response.StatusCode = 200;
                http.Response.ContentType = "text/event-stream";
                await WriteChatStreamAsync(http.Response.Body);
                return new ResponseAlreadyWritten();
            }

            async Task WriteChatStreamAsync(Stream stream)
            {
                    var model = request.Model ?? "default-agent";
                    // The session id (and, when the requested session had expired, the resumed flag)
                    // travels in a dedicated FIRST chunk: the client learns the id it must use for the
                    // next prompt before any text arrives, so a conversation resumed on a new session
                    // continues seamlessly. Absent on session-less requests.
                    if (sessionId != null)
                    {
                        var sessionChunk = new
                        {
                            id = $"chatcmpl-{Guid.NewGuid():N}",
                            @object = "chat.completion.chunk",
                            created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                            model,
                            session_id = sessionId,
                            session_resumed = sessionResumed,
                            choices = new[]
                            {
                                new { index = 0, delta = new { content = (string?)null }, finish_reason = (string?)null }
                            }
                        };
                        await stream.WriteAsync(Encoding.UTF8.GetBytes($"data: {JsonSerializer.Serialize(sessionChunk, jsonOptions)}\n\n"), ct);
                        await stream.FlushAsync(ct);
                    }
                    // Keepalive while the agent works: one SSE comment line every 15 s. The spec
                    // requires clients to ignore comment lines and our own chat panel skips
                    // anything that is not "data: " — the only purpose is that bytes keep
                    // flowing, so no idle read timeout (client, proxy, load balancer) kills a
                    // job that legitimately runs for half an hour.
                    try
                    {
                        while (await Task.WhenAny(run, Task.Delay(TimeSpan.FromSeconds(15), ct)) != run)
                        {
                            await stream.WriteAsync(Encoding.UTF8.GetBytes(": keepalive\n\n"), ct);
                            await stream.FlushAsync(ct);
                        }
                    }
                    catch (OperationCanceledException)
                    {
                        return;   // the client hung up mid-run: nothing left to send
                    }
                    var outcome = await run;
                    var result = outcome.Result;
                    var content = outcome.Content;
                    var finishReason = outcome.FinishReason;
                    foreach (var word in content.Split(' '))
                    {
                        if (ct.IsCancellationRequested) break;
                        var chunk = new
                        {
                            id = $"chatcmpl-{Guid.NewGuid():N}",
                            @object = "chat.completion.chunk",
                            created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                            model,
                            choices = new[]
                            {
                                new { index = 0, delta = new { content = word + " " }, finish_reason = (string?)null }
                            }
                        };
                        await stream.WriteAsync(Encoding.UTF8.GetBytes($"data: {JsonSerializer.Serialize(chunk, jsonOptions)}\n\n"), ct);
                        await stream.FlushAsync(ct);
                        await Task.Delay(30, ct);
                    }
                    // Agent-attached files (done method's "attachments" field): delivered as a
                    // dedicated chunk carrying the standard MCP embedded-resource shape. Giraffe AI
                    // reads parsed.attachments from any SSE chunk, so one chunk before the end suffices.
                    if (result.Attachments is { Count: > 0 })
                    {
                        var attachmentsChunk = new
                        {
                            id = $"chatcmpl-{Guid.NewGuid():N}",
                            @object = "chat.completion.chunk",
                            created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                            model,
                            attachments = result.Attachments,
                            choices = new[]
                            {
                                new { index = 0, delta = new { content = (string?)null }, finish_reason = (string?)null }
                            }
                        };
                        await stream.WriteAsync(Encoding.UTF8.GetBytes($"data: {JsonSerializer.Serialize(attachmentsChunk, jsonOptions)}\n\n"), ct);
                        await stream.FlushAsync(ct);
                    }
                    var finalChunk = new
                    {
                        id = $"chatcmpl-{Guid.NewGuid():N}",
                        @object = "chat.completion.chunk",
                        created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                        model,
                        choices = new[]
                        {
                            new { index = 0, delta = new { content = "" }, finish_reason = finishReason }
                        }
                    };
                    await stream.WriteAsync(Encoding.UTF8.GetBytes($"data: {JsonSerializer.Serialize(finalChunk, jsonOptions)}\n\n"), ct);
                    // Token usage on the stream, the OpenAI way: only when the client asked for it
                    // (stream_options.include_usage), in a last chunk whose choices array is empty,
                    // immediately before [DONE]. A client that did not ask sees exactly the stream
                    // it always saw.
                    if (request.StreamOptions?.IncludeUsage == true)
                    {
                        var usageChunk = new
                        {
                            id = $"chatcmpl-{Guid.NewGuid():N}",
                            @object = "chat.completion.chunk",
                            created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                            model,
                            choices = Array.Empty<object>(),
                            usage = UsagePayload(result, prompt, content)
                        };
                        await stream.WriteAsync(Encoding.UTF8.GetBytes($"data: {JsonSerializer.Serialize(usageChunk, jsonOptions)}\n\n"), ct);
                        await stream.FlushAsync(ct);
                    }
                    await stream.WriteAsync(Encoding.UTF8.GetBytes("data: [DONE]\n\n"), ct);
                    await stream.FlushAsync(ct);
            }

            var done = await run;
            var result = done.Result;
            var content = done.Content;
            var finishReason = done.FinishReason;
            var response = new
            {
                id = $"chatcmpl-{Guid.NewGuid():N}",
                @object = "chat.completion",
                created = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                model = request.Model ?? "default-agent",
                session_id = sessionId,
                session_resumed = sessionResumed,
                // Agent-attached files in the standard MCP embedded-resource shape (same payload
                // the streaming path sends as a dedicated chunk).
                attachments = result.Attachments,
                choices = new[]
                {
                    new
                    {
                        index = 0,
                        message = new { role = "assistant", content },
                        finish_reason = finishReason
                    }
                },
                usage = UsagePayload(result, prompt, content)
            };
            return Results.Ok(response);
        }
        finally
        {
            // Safe to dispose here: both response paths await the worker task before returning,
            // so the agent turn is over by the time this runs (the streaming path writes its body
            // inside the handler for exactly this reason).
            session?.Gate.Release();
            owned?.Dispose();
        }
    }
    catch (Exception ex)
    {
        return Results.Problem(detail: ex.Message, statusCode: 500, title: "Agent execution failed");
    }
});

// ─────────────────────────────────────────────────────────────────────
// POST /v1/files — multipart upload + server-side Markdown conversion
// ─────────────────────────────────────────────────────────────────────
// Architectural model (see AIOrchestrator/docs-dev/ARCHITECTURE.md — "AgentBridge"):
// this endpoint mirrors the OpenAI Files API "upload once, reference later" pattern.
//  - The multipart shape (form field `file` + `purpose`) matches the OpenAI upload call.
//  - The response carries the OpenAI metadata schema (id, object, bytes, created_at,
//    filename, purpose, status) plus two additive extensions used by Giraffe AI:
//    `extracted_content` (the server-side Markdown) and `content_format`.
//  - Conversion is always server-side (never in the browser) — same rule as the
//    Blazor UI; documents go through AllToMarkdown, images through Z.ai GLM-OCR.
//  - The bytes + Markdown are cached in memory so a later chat request can reference
//    them by a lightweight `file_id` instead of re-sending the content.
//  - The original `filename` travels as response metadata (OpenAI convention), NOT as
//    YAML frontmatter in the converted content: the name is first-class state in
//    FileCache/FileAttachment, and injecting it into the Markdown would pollute the
//    document text. See LLMUtility.SendQuery's `supportDocuments` path for the one
//    place where YAML frontmatter is appropriate (files persisted on disk).
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/files", async (IFormFile file, [FromQuery] string purpose = "assistants") =>
{
    if (file == null || file.Length == 0)
        return Results.BadRequest(new { error = "No file provided" });
    if (file.Length > 25_000_000)
        return Results.BadRequest(new { error = "File too large (max 25MB)" });

    await using var ms = new MemoryStream();
    await file.CopyToAsync(ms);
    var content = ms.ToArray();

    var fileId = $"file-{Guid.NewGuid():N}";
    var attachment = new FileAttachment(file.FileName, content);
    var markdown = AgentHarness.ConvertAttachmentToMarkdown(attachment);
    Log.LogStep($"POST /v1/files: '{file.FileName}' ({file.Length} bytes) → " +
        (string.IsNullOrEmpty(markdown) ? "no markdown (unsupported/empty/unreadable)" : $"converted ({markdown.Length} chars)"));

    FileCache.Store(new CachedFile
    {
        Id = fileId,
        FileName = file.FileName,
        MimeType = file.ContentType,
        Content = content,
        ExtractedText = markdown ?? "",
        SizeBytes = file.Length,
        StoredAt = DateTime.UtcNow
    });

    return Results.Ok(new
    {
        id = fileId,
        @object = "file",
        bytes = file.Length,
        created_at = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
        filename = file.FileName,
        purpose,
        status = !string.IsNullOrEmpty(markdown) ? "processed" : "unsupported",
        extracted_content = markdown,
        content_format = "markdown"
    });
}).DisableAntiforgery();

// ─────────────────────────────────────────────────────────────────────
// GET /v1/files/{fileId}
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/files/{fileId}", (string fileId) =>
{
    var file = FileCache.Get(fileId);
    if (file == null)
        return Results.NotFound(new { error = $"File '{fileId}' not found" });

    return Results.Ok(new
    {
        id = file.Id,
        @object = "file",
        bytes = file.SizeBytes,
        created_at = new DateTimeOffset(file.StoredAt).ToUnixTimeSeconds(),
        filename = file.FileName,
        status = file.ExtractedText.Length > 0 ? "processed" : "unsupported",
        extracted_content = file.ExtractedText,
        content_format = "markdown"
    });
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/files/{fileId}/content — the original uploaded bytes (OpenAI Files API).
// Closes a documented gap (see ARCHITECTURE.md): raw retrieval complements the
// Markdown in /v1/files/{id}.
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/files/{fileId}/content", (string fileId) =>
{
    var file = FileCache.Get(fileId);
    if (file == null)
        return Results.NotFound(new { error = $"File '{fileId}' not found" });

    return Results.File(file.Content,
        string.IsNullOrEmpty(file.MimeType) ? "application/octet-stream" : file.MimeType,
        file.FileName);
});

// ─────────────────────────────────────────────────────────────────────
// DELETE /v1/files/{fileId} — file lifecycle (OpenAI Files API).
// ─────────────────────────────────────────────────────────────────────
app.MapDelete("/v1/files/{fileId}", (string fileId) =>
{
    if (!FileCache.Remove(fileId))
        return Results.NotFound(new { error = $"File '{fileId}' not found" });

    return Results.Ok(new { id = fileId, @object = "file", deleted = true });
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/files — list uploaded files
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/files", () =>
{
    var files = FileCache.GetAll();
    return Results.Ok(new
    {
        @object = "list",
        data = files.Select(f => new
        {
            id = f.Id,
            @object = "file",
            bytes = f.SizeBytes,
            created_at = new DateTimeOffset(f.StoredAt).ToUnixTimeSeconds(),
            filename = f.FileName,
            status = f.ExtractedText.Length > 0 ? "processed" : "unsupported"
        })
    });
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/models — agent sets AND LLM providers with their characteristics
// ─────────────────────────────────────────────────────────────────────
// Two kinds of "models":
//  - agent sets (default-agent, web-agent, ...): select which agent tools ExecuteAction
//    instantiates via the `model` field of /v1/chat/completions;
//  - LLM providers (DeepSeekBridge, Zai, ...): the actual LLMs behind the agents. The
//    provider in use is switched via the llm_provider field / POST /v1/control; each
//    entry carries the LLM characteristics (model_name, protocol, context_window,
//    base_address) so clients can pick a provider that fits their task and context size.
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/models", () =>
{
    var agents = agentModelIds.Select(id => new
    {
        id,
        @object = "model",
        owned_by = "ai-orchestrator",
        created = 0
    });

    var providers = ProviderConfigs.All.Select(p => new
    {
        id = p.ProviderName,
        @object = "model",
        owned_by = "llm-provider",
        created = 0,
        // additive LLM characteristics (ignored by strict OpenAI clients)
        provider = p.ProviderName,
        model_name = p.ModelName,
        protocol = p.Protocol.ToString(),
        context_window = p.ContextWindow,
        base_address = p.BaseAddress.ToString(),
        interaction_mode = p.EffectiveAgentInteractionMode.ToString()
    });

    return Results.Ok(new { @object = "list", data = agents.Cast<object>().Concat(providers.Cast<object>()) });
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/models/{model} — single model details (agent set or LLM provider)
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/models/{model}", (string model) =>
{
    var id = model.ToLowerInvariant();
    if (agentModelIds.Contains(id))
    {
        return Results.Ok(new
        {
            id,
            @object = "model",
            owned_by = "ai-orchestrator",
            created = 0
        });
    }

    if (ProviderConfigs.TryGet(model, out var provider))
    {
        return Results.Ok(new
        {
            id = provider!.ProviderName,
            @object = "model",
            owned_by = "llm-provider",
            created = 0,
            provider = provider.ProviderName,
            model_name = provider.ModelName,
            protocol = provider.Protocol.ToString(),
            context_window = provider.ContextWindow,
            base_address = provider.BaseAddress.ToString(),
            interaction_mode = provider.EffectiveAgentInteractionMode.ToString()
        });
    }

    return Results.NotFound(new { error = $"Model '{model}' not found" });
});

// ─────────────────────────────────────────────────────────────────────
// POST /v1/audio/speech — text-to-speech (standard OpenAI endpoint)
//
// In-process Kokoro neural TTS (same engine/voices as the Windows VoiceAgent, but
// cross-platform). Returns WAV bytes. Voice names accept OpenAI names ("alloy",
// "echo", ...) or raw Kokoro ids ("if_sara", "af_heart", ...) — see /v1/audio/voices.
// Returns 501 when the model assets are not present on this platform.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/audio/speech", (SpeechRequest request) =>
{
    if (string.IsNullOrWhiteSpace(request.Input))
        return Results.BadRequest(new { error = "input is required" });

    if (!TtsEngine.IsAvailable)
        return Results.Json(new { error = "tts_unavailable", detail = TtsEngine.UnavailableReason }, statusCode: 501);

    var format = (request.ResponseFormat ?? "wav").ToLowerInvariant();
    if (format != "wav")
        return Results.BadRequest(new { error = $"Unsupported response_format '{format}'. Supported: wav." });

    try
    {
        var audio = TtsEngine.Synthesize(request.Input, request.Voice, request.Speed, request.Lang);
        return Results.Bytes(audio, "audio/wav", $"speech-{DateTime.UtcNow:yyyyMMddHHmmss}.wav");
    }
    catch (Exception ex)
    {
        return Results.Problem(detail: ex.Message, statusCode: 500, title: "TTS synthesis failed");
    }
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/audio/voices — TTS voices available on this platform (proprietary)
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/audio/voices", () =>
{
    return Results.Ok(new
    {
        @object = "list",
        available = TtsEngine.IsAvailable,
        engine = "kokoro",
        detail = TtsEngine.IsAvailable ? "" : TtsEngine.UnavailableReason,
        data = TtsEngine.Voices.Select(v => new { id = v, @object = "voice" })
    });
});

// ─────────────────────────────────────────────────────────────────────
// POST /v1/voice/listen — one-shot speech recognition (proprietary, Windows only)
//
// Uses the server microphone through the AIOffice.VoiceAgent.Win.exe subprocess
// (the same chain as the AIOffice Voice panel). Reported unavailable (501) when the
// platform or the executable is missing. The client then falls back to text input.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/voice/listen", async (VoiceListenRequest request, CancellationToken ct) =>
{
    if (!VoiceBridge.IsAvailable)
        return Results.Json(new { error = "voice_unavailable", detail = VoiceBridge.UnavailableReason }, statusCode: 501);

    try
    {
        var text = await VoiceBridge.ListenOnceAsync(request.Lang, request.TimeoutSeconds ?? 15, ct);
        // Speech recognition speaks the machine's language: reflect the language actually
        // used (never a hardcoded default) in the response.
        var lang = request.Lang ?? SystemLang.Get();
        return Results.Ok(new { text, lang, provider = "voiceagent-win" });
    }
    catch (TimeoutException ex)
    {
        return Results.Json(new { error = "timeout", detail = ex.Message }, statusCode: 408);
    }
    catch (Exception ex)
    {
        return Results.Problem(detail: ex.Message, statusCode: 500, title: "Speech recognition failed");
    }
});

// ─────────────────────────────────────────────────────────────────────
// POST /v1/suggest — next-prompt suggestion (proprietary)
//
// Client-driven enhancement: a UI that supports ghost-text suggestions asks what the user
// is likely to type next. Chats that never ask (SIP calls, Telegram, any client without
// this feature) pay no extra computation. Setting off → empty answer, no model call.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/suggest", async (SuggestRequest request, CancellationToken ct) =>
{
    if (!AIOrchestrator.Setup.PromptSuggestion || request.Messages == null || request.Messages.Count == 0)
        return Results.Ok(new { suggestion = "" });
    try
    {
        var transcript = request.Messages
            .Select(m => (Role: m.Role ?? "user", Text: m.Content ?? ""))
            .ToList();
        var suggestion = await AIOrchestrator.PromptSuggestionGenerator.GenerateAsync(transcript, ct);
        return Results.Ok(new { suggestion });
    }
    catch (OperationCanceledException)
    {
        return Results.Ok(new { suggestion = "" });
    }
    catch (Exception ex)
    {
        Log.LogStep($"Prompt suggestion failed: {ex.Message}");
        return Results.Ok(new { suggestion = "" });
    }
});

// ─────────────────────────────────────────────────────────────────────
// GET /v1/control — read session state and/or platform capabilities (proprietary)
//
// ?session_id=... → that session's state (LLM in use, history estimate, features).
// without session  → platform capabilities (TTS/voice availability, providers).
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/control", (string? session_id) =>
{
    if (!string.IsNullOrEmpty(session_id))
    {
        var session = SessionStore.Get(session_id);
        if (session == null)
            return Results.NotFound(new { error = $"Session '{session_id}' not found" });
        return Results.Ok(SessionState(session));
    }
    return Results.Ok(new { capabilities = BuildCapabilities() });
});

// ─────────────────────────────────────────────────────────────────────
// POST /v1/control — pilot endpoint (proprietary, extensible)
//
// The "control plane" of the server: switch the LLM currently in use for a session,
// toggle feature flags (voice, tts, ...), reset the conversation, create a session or
// close sessions (which is what makes a conversation record its memory).
// Body (all fields optional):
//   { "create": true }                         → create a new session (returns its id)
//   { "session_id": "...", "llm_provider": "Zai" }      → switch the LLM in use (session only)
//   { "session_id": "...", "features": { "voice": true, "tts": false } }
//   { "session_id": "...", "reset_history": true }
//   { "session_id": "...", "close_session": true }      → close that session (records memory)
//   { "close_sessions": true }                 → close every live session (records memory)
//   { "set_default_provider": "Zai" }          → process-wide default for NEW sessions (persisted);
//                                                the current session is NOT switched
//
// A provider switch is refused (409) when the accumulated conversation overflows the
// target provider's context window (the exact case "switch on the fly conflicts with
// the context window of the model in use"); reset the conversation and retry.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/v1/control", async (ControlRequest request, CancellationToken ct) =>
{
    // Make a provider the default for NEW sessions (persisted explicit marker). This is the
    // TUI main-settings "Set default" action — /model keeps switching only the current session.
    if (!string.IsNullOrEmpty(request.SetDefaultProvider))
    {
        var defaultName = request.SetDefaultProvider.Trim();
        if (!ProviderConfigs.TryGet(defaultName, out _))
            return Results.BadRequest(new { error = $"Unknown LLM provider '{defaultName}'." });
        ProviderConfigs.SetDefault(defaultName, persist: true);
        startupProvider = ProviderConfigs.Get(defaultName).ProviderName;
        return Results.Ok(new { default_provider = startupProvider });
    }

    if (request.Create == true)
    {
        var created = SessionStore.Create(startupProvider, anonymize);
        return Results.Ok(SessionState(created));
    }

    // Closing a session is the only way a conversation records its memory without waiting
    // for the idle timeout: the recording lives in AgentHarness.Dispose. The TUI calls this
    // before quitting, so a conversation the user just had is never forgotten.
    if (request.CloseSessions == true)
    {
        Log.LogStep("Control: closing every live session", monitor: true);
        var (closed, skipped) = await SessionStore.CloseAllAsync(sessionCloseTimeout, ct);
        return Results.Ok(new { ok = true, closed, skipped });
    }

    if (request.CloseSession == true)
    {
        if (string.IsNullOrEmpty(request.SessionId))
            return Results.BadRequest(new { error = "session_id is required to close a session" });
        var closed = await SessionStore.CloseAsync(request.SessionId, sessionCloseTimeout, ct);
        return Results.Ok(new { ok = true, closed = closed ? 1 : 0, skipped = closed ? 0 : 1 });
    }

    if (string.IsNullOrEmpty(request.SessionId))
        return Results.BadRequest(new { error = "session_id is required for mutations (or use {\"create\": true} to create a new session)" });

    var session = SessionStore.Get(request.SessionId);
    if (session == null)
        return Results.NotFound(new { error = $"Session '{request.SessionId}' not found" });

    session.Gate.Wait();
    try
    {
        if (request.ResetHistory == true)
            session.Orchestrator.ResetConversation();

        if (!string.IsNullOrEmpty(request.LlmProvider))
        {
            var target = ResolveProvider(request.LlmProvider, startupProvider, out var error)!;
            if (error != null)
                return Results.BadRequest(new { error });

            if (!string.Equals(session.Orchestrator.Provider, target, StringComparison.OrdinalIgnoreCase))
            {
                var fitError = ContextFitError(session, target, "");
                if (fitError != null)
                    return Results.Json(fitError, statusCode: 409);
                session.Orchestrator.SwitchProvider(target);
            }
        }

        if (request.Features != null)
            foreach (var kv in request.Features)
                session.Features[kv.Key] = kv.Value;

        return Results.Ok(SessionState(session));
    }
    finally
    {
        session.Gate.Release();
    }
});

app.MapGet("/health", () => Results.Ok(new { status = "healthy", timestamp = DateTime.UtcNow }));

// ─────────────────────────────────────────────────────────────────────
// POST /mcp — native MCP connector (JSON-RPC 2.0, minimal profile)
//
// This intentionally starts small to be immediately useful:
//  - initialize
//  - tools/list    → exposes a single high-level tool: agent_run
//  - tools/call    → executes agent_run through AgentHarness
//
// Goal: make AgentBridge consumable from standard MCP clients without any external
// adapter process, while keeping the contract stable and easy to evolve.
// ─────────────────────────────────────────────────────────────────────
app.MapPost("/mcp", async (HttpContext http, CancellationToken ct) =>
{
    JsonDocument doc;
    try
    {
        doc = await JsonDocument.ParseAsync(http.Request.Body, cancellationToken: ct);
    }
    catch (Exception ex)
    {
        return Results.BadRequest(new { error = $"Invalid JSON body: {ex.Message}" });
    }

    using (doc)
    {
        var root = doc.RootElement;
        if (root.ValueKind != JsonValueKind.Object)
            return Results.BadRequest(new { error = "JSON-RPC request must be an object" });

        var hasId = root.TryGetProperty("id", out var reqId);
        var id = hasId ? reqId.Clone() : default;
        if (!root.TryGetProperty("method", out var methodEl) || methodEl.ValueKind != JsonValueKind.String)
            return McpError(id, hasId, -32600, "Invalid Request: missing method");

        var method = methodEl.GetString() ?? "";
        var @params = root.TryGetProperty("params", out var paramsEl) && paramsEl.ValueKind == JsonValueKind.Object
            ? paramsEl
            : default;

        switch (method)
        {
            case "initialize":
                return McpOk(id, hasId, new
                {
                    protocolVersion = "2025-06-18",
                    capabilities = new
                    {
                        tools = new { listChanged = false }
                    },
                    serverInfo = new
                    {
                        name = "AgentBridge",
                        version = typeof(Program).Assembly.GetName().Version?.ToString() ?? "0.0.0"
                    }
                });

            case "tools/list":
                return McpOk(id, hasId, new
                {
                    tools = new object[]
                    {
                        new
                        {
                            name = "agent_run",
                            description = "Run an autonomous AgentBridge execution for a user goal.",
                            inputSchema = new
                            {
                                type = "object",
                                properties = new
                                {
                                    prompt = new { type = "string", description = "User request for the agent." },
                                    model = new { type = "string", description = "Agent preset id (e.g. default-agent, web-agent, multi-agent)." },
                                    llm_provider = new { type = "string", description = "Optional LLM provider override (e.g. Zai, DeepSeekBridge, Ollama)." },
                                    max_iterations = new { type = "integer", description = "Optional max loop iterations (default 200)." },
                                    session_id = new { type = "string", description = "Optional session id for multi-turn continuity." }
                                },
                                required = new[] { "prompt" }
                            }
                        }
                    }
                });

            case "tools/call":
            {
                if (@params.ValueKind != JsonValueKind.Object)
                    return McpError(id, hasId, -32602, "Invalid params: expected object");
                if (!@params.TryGetProperty("name", out var toolNameEl) || toolNameEl.ValueKind != JsonValueKind.String)
                    return McpError(id, hasId, -32602, "Invalid params: missing tool name");

                var toolName = toolNameEl.GetString() ?? "";
                if (!string.Equals(toolName, "agent_run", StringComparison.Ordinal))
                    return McpError(id, hasId, -32601, $"Tool '{toolName}' not found");

                var argsObj = @params.TryGetProperty("arguments", out var argsEl) && argsEl.ValueKind == JsonValueKind.Object
                    ? argsEl
                    : default;
                var prompt = JsonString(argsObj, "prompt");
                if (string.IsNullOrWhiteSpace(prompt))
                    return McpError(id, hasId, -32602, "Invalid arguments: 'prompt' is required");

                var model = JsonString(argsObj, "model") ?? "default-agent";
                var providerArg = JsonString(argsObj, "llm_provider");
                var sessionId = JsonString(argsObj, "session_id");
                var maxIterations = JsonInt(argsObj, "max_iterations") ?? 200;
                maxIterations = Math.Clamp(maxIterations, 1, 200);

                var resolvedProvider = ResolveProvider(providerArg, startupProvider, out var providerError);
                if (providerError != null)
                    return McpToolError(id, hasId, providerError);
                var provider = resolvedProvider!;

                var agentToolNames = ResolveAgentTypes(model);
                ActiveSession? session = null;
                AgentHarness? owned = null;
                var sessionGateHeld = false;

                try
                {
                    if (!string.IsNullOrWhiteSpace(sessionId))
                    {
                        session = SessionStore.Get(sessionId);
                        if (session == null)
                            return McpToolError(id, hasId, $"Session '{sessionId}' not found");

                        await session.Gate.WaitAsync(ct);
                        sessionGateHeld = true;
                        var target = session.Orchestrator.Provider;
                        if (!string.Equals(target, provider, StringComparison.OrdinalIgnoreCase))
                            target = provider;
                        var fitError = ContextFitError(session, target, prompt!);
                        if (fitError != null)
                            return McpOk(id, hasId, new
                            {
                                content = new[] { new { type = "text", text = JsonSerializer.Serialize(fitError) } },
                                isError = true
                            });

                        if (!string.Equals(session.Orchestrator.Provider, provider, StringComparison.OrdinalIgnoreCase))
                            session.Orchestrator.SwitchProvider(provider);
                    }
                    else
                    {
                        owned = new AgentHarness(provider, anonymize);
                    }

                    var orchestrator = session?.Orchestrator ?? owned!;
                    var result = AgentTools.ExecuteSplit(orchestrator, prompt!, agentToolNames, maxIterations);
                    session?.AddTurnUsage(result.Usage);
                    var text = result.Message ?? AgentResultDisplay.ResultText(result) ?? Dictionary.NoOutputGenerated;

                    return McpOk(id, hasId, new
                    {
                        content = new[] { new { type = "text", text } },
                        structuredContent = new
                        {
                            success = result.Success,
                            code = result.Code.ToString(),
                            iterations = result.Iterations,
                            elapsed_ms = result.TotalElapsedMs,
                            session_id = session?.Id,
                            attachments = result.Attachments,
                            usage = UsagePayload(result, prompt!, text)
                        },
                        isError = !result.Success
                    });
                }
                catch (Exception ex)
                {
                    return McpToolError(id, hasId, ex.Message);
                }
                finally
                {
                    if (sessionGateHeld)
                        session?.Gate.Release();
                    owned?.Dispose();
                }
            }

            default:
                return McpError(id, hasId, -32601, $"Method '{method}' not found");
        }
    }
});

// ─────────────────────────────────────────────────────────────────────
// SIP telephony endpoints (proprietary, see docs/sip.md) — drive the SipBridge
// from the TUI / client: status, outgoing calls, hangup, answer gate.
// ─────────────────────────────────────────────────────────────────────
app.MapGet("/v1/sip/status", () => Results.Ok(new { sip = SipBridge.Status }));

app.MapPost("/v1/sip/call", async (SipCallRequest request) =>
{
    if (string.IsNullOrWhiteSpace(request.Uri))
        return Results.BadRequest(new { error = "uri is required (e.g. sip:user@host or a number routed via the registrar)" });
    if (!SipBridge.IsEnabled)
        return Results.Json(new { error = "sip_disabled", detail = "Set Sip:Enabled true in appsettings.json" }, statusCode: 501);
    var error = await SipBridge.CallAsync(request.Uri);
    return error == null
        ? Results.Ok(new { ok = true, message = $"calling {request.Uri}" })
        : Results.BadRequest(new { ok = false, error });
});

app.MapPost("/v1/sip/hangup", () =>
{
    SipBridge.Hangup();
    return Results.Ok(new { ok = true });
});

app.MapPost("/v1/sip/answer", (SipAnswerRequest request) =>
{
    SipBridge.SetAnswerEnabled(request.On ?? true);
    return Results.Ok(new { ok = true, answer_enabled = request.On ?? true });
});

app.MapGet("/v1/sip/config", () => Results.Ok(new { sip = SipBridge.ConfigSnapshot }));

app.MapPost("/v1/sip/config", async (SipConfigRequest request) =>
{
    if (string.IsNullOrWhiteSpace(request.Key))
        return Results.BadRequest(new { error = "key is required (e.g. Enabled, ListenPort, Registrar, Username, Password, AnswerMode, Pin, MaxPinAttempts, LockoutHours, AllowedCallers, Agent, Lang, SttExePath, RtpPortRange)" });
    var (error, restart, message) = await SipBridge.SetConfigAsync(request.Key.Trim(), request.Value);
    return error == null
        ? Results.Ok(new { ok = true, message, restart_required = restart })
        : Results.BadRequest(new { ok = false, error });
});

app.MapPost("/v1/sip/config/reload", async () =>
{
    var (error, restart, message) = await SipBridge.ReloadConfigAsync();
    return error == null
        ? Results.Ok(new { ok = true, message, restart_required = restart })
        : Results.BadRequest(new { ok = false, error });
});

// ─────────────────────────────────────────────────────────────────────
// Auto-update: at startup, check the latest GitHub release and apply it when newer
// (download → swap → restart). Background and best-effort: any failure leaves the
// current version running; disable with --no-update or the TUI File → Auto-Update
// menu (docs/autoupdate.md).
// ─────────────────────────────────────────────────────────────────────
if (AutoUpdate.Enabled)
    _ = Task.Run(async () => { try { await AutoUpdate.CheckAndApplyAsync(); } catch (Exception ex) { Log.LogStep($"AutoUpdate: {ex.Message}"); } });

// ─────────────────────────────────────────────────────────────────────
// Web client (Giraffe AI): installed on first run next to the executable and kept at
// the latest GitHub release — background and best-effort (see WebClientUpdater.cs).
// The TUI /web command joins this same task before launching the client.
// ─────────────────────────────────────────────────────────────────────
_ = WebClientUpdater.Startup;

// ─────────────────────────────────────────────────────────────────────
// Auto-start on boot: register once on first run (release builds only — debug
// runs are exempt, and SystemExtra.Util itself also skips when a debugger is
// attached or the app runs from bin/). Only acts when autostart was NEVER
// configured, so a later choice in the TUI settings (General tab) sticks.
// Windows → Task Scheduler logon task; Linux/macOS → systemd / launchd service.
// ─────────────────────────────────────────────────────────────────────
#if !DEBUG
if (!SystemExtra.Util.IsService())
    SystemExtra.Util.SetAutoStart(true);
#endif

// ─────────────────────────────────────────────────────────────────────
// Launch mode: terminal UI (default, interactive console) or plain server.
// The TUI runs the HTTP server in the same process: the API keeps answering
// while you chat — that is the "CLI + API simultaneously" requirement.
// ─────────────────────────────────────────────────────────────────────
if (SipBridge.IsEnabled)
{
    var sipError = await SipBridge.StartAsync();
    if (sipError != null)
        Console.WriteLine($"SIP server not started: {sipError}");
}

// Telegram: background start so a pending first-login (verification code) never blocks the
// boot — the TUI shows the pending-login phase and drives the code via /telegram.
if (TelegramBridge.IsEnabled)
{
    _ = Task.Run(async () =>
    {
        var tgError = await TelegramBridge.StartAsync();
        if (tgError != null)
            Console.WriteLine($"Telegram bridge not started: {tgError}");
    });
}

if (useTui)
{
    string? hostError = null;
    // The actual URL comes from config ("urls" ← appsettings/ASPNETCORE_URLS). app.Urls
    // before StartAsync only contains Kestrel's default (e.g. localhost:5000),
    // so DON'T use it: the TUI must talk to the same port Kestrel binds to.
    // (LESSON: this was a real bug — the TUI connected to :5000 and reported the
    // server unreachable while the server was fine on :5290.)
    var tuiUrl = app.Configuration["urls"]
#if DEBUG
        ?? "http://localhost:5291";
#else
        ?? "http://localhost:5290";
#endif
    try
    {
        await app.StartAsync();
        // app.Urls is authoritative only AFTER StartAsync: it carries the address Kestrel
        // really bound. The configured value can differ (port taken, launch profile, env
        // var), and a TUI pointing at a port nothing listens on fails every call with
        // "connection refused" — so prefer the bound address. Wildcard hosts are mapped
        // to localhost: the TUI runs on this machine.
        var bound = app.Urls.FirstOrDefault(u => u.StartsWith("http://", StringComparison.OrdinalIgnoreCase))
                    ?? app.Urls.FirstOrDefault();
        if (!string.IsNullOrEmpty(bound))
            tuiUrl = bound.Replace("://0.0.0.0", "://localhost").Replace("://[::]", "://localhost");
    }
    catch (Exception ex)
    {
        // Address already in use: another agent instance is running — the UI
        // connects to it instead of hosting a second (conflicting) server.
        hostError = ex.Message;
    }
    // True when the exception chain bottoms out on a missing embedded resource — the
    // signature of a damaged or half-finished install/update where the localized UI
    // strings cannot be read (issue #96). The terminal UI is built from those strings
    // in ConsoleTui's static initializer, so such a failure surfaces as a
    // TypeInitializationException wrapping a MissingManifestResourceException before
    // the alternate screen is even entered. Used to degrade to server-only instead of
    // crash-looping (the crash handler would restart the process every 60 s into the
    // same unreadable-resource failure).
    static bool HasMissingUiResource(Exception? ex)
    {
        for (var e = ex; e != null; e = e.InnerException)
            if (e is System.Resources.MissingManifestResourceException) return true;
        return false;
    }
    try
    {
#if DEBUG
        // ── Puppet-mode TCP listener (port 5292) — DEBUG BUILDS ONLY ──
        // Accepts JSON commands on localhost:5292 and injects them into
        // Terminal.Gui's event loop via PuppetMode (Tui.cs), which marshals
        // every call onto the UI thread with Application.Invoke. The release
        // binary has no puppet surface at all: this listener never starts.
        // (5292, NOT 5291: a DEBUG instance serves HTTP on 5291 by default — see
        // the port-separation block above — so the puppet surface must not clash.)
        PuppetMode.Enabled = true;
        var puppetCts = new CancellationTokenSource();
        var puppetTask = Task.Run(async () =>
        {
            using var listener = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 5292);
            listener.Start();
            Console.WriteLine("[Puppet] TCP listener started on localhost:5292");
            Log.LogStep("Puppet TCP listener started on localhost:5292", monitor: true);
            while (!puppetCts.Token.IsCancellationRequested)
            {
                try
                {
                    var tcpClient = await listener.AcceptTcpClientAsync(puppetCts.Token);
                    _ = Task.Run(async () => HandlePuppetClientAsync(tcpClient, puppetCts.Token));
                }
                catch (OperationCanceledException) { break; }
                catch { /* best-effort */ }
            }
        });

        await ConsoleTui.RunAsync(tuiUrl, hostError);
        puppetCts.Cancel();
        try { await puppetTask; } catch { }
#else
        await ConsoleTui.RunAsync(tuiUrl, hostError);
#endif
    }
    catch (Exception ex) when (HasMissingUiResource(ex))
    {
        // The localized UI strings could not be loaded: the embedded resource set is
        // unreadable, which only happens on a damaged or half-finished install/update
        // (issue #96). The terminal UI cannot be built, but the HTTP server is healthy,
        // so keep serving instead of dying and letting the crash handler restart the
        // process every 60 s into the same failure. The console writers were silenced
        // for the TUI — restore them so this message is actually visible.
        try { Console.SetOut(realStandardOutput); Console.SetError(realStandardError); } catch { }
        Console.Error.WriteLine("AgentBridge: the interface language files could not be loaded (damaged or incomplete install/update).");
        Console.Error.WriteLine("The terminal UI cannot start, but the server keeps running — the API stays available.");
        Console.Error.WriteLine("Reinstall the latest version to restore the terminal UI.");
        Log.LogStep("TUI disabled: UI resources unreadable (" + ex.GetType().Name + ") — running server-only", monitor: true);
        await app.WaitForShutdownAsync();
    }
    finally
    {
        SipBridge.Stop();
        TelegramBridge.Stop();
        try { await app.StopAsync(); } catch { }
    }
    return 0;
}

// Headless server path. A port conflict (another AgentBridge instance, or any program
// holding the configured port) used to surface here as an unhandled
// IOException/AddressInUseException/SocketException crash (issue #18): the crash
// handler then restarts the process every 60 s into the same conflict. The TUI path
// already degrades gracefully (hostError); mirror that here — fail fast with an
// actionable message and a clean exit code instead of a crash report.
// The address must be captured BEFORE the host runs: after a failed bind the root
// IServiceProvider is disposed and both app.Urls and app.Configuration resolve
// through it, throwing ObjectDisposedException inside the catch (found in the
// retest of issue #18). The config value covers appsettings.json, ASPNETCORE_URLS
// and --Urls alike.
var headlessUrl = app.Configuration["Urls"] ?? "the configured address";
try
{
    app.Run();
    return 0;
}
catch (Exception ex) when (IsAddressInUse(ex))
{
    Console.Error.WriteLine();
    Console.Error.WriteLine($"AgentBridge cannot start: {headlessUrl} is already in use.");
    Console.Error.WriteLine("Another AgentBridge instance (or another program) is listening on this port.");
    Console.Error.WriteLine("Close the other instance, or pick another port: --Urls http://localhost:5293");
    Console.Error.WriteLine("(or set the ASPNETCORE_URLS environment variable / the \"Urls\" key in appsettings.json).");
    return 1;
}
catch (ObjectDisposedException)
{
    // Shutdown race (issue #20): the host and its root service provider were
    // disposed while app.Run() was still parked on the stop signal, so the wait
    // surfaced a bare ObjectDisposedException instead of returning normally. The
    // process was being stopped anyway — exit cleanly here rather than let it
    // reach the unhandled-exception handler, which would fire a crash report and
    // the 60 s auto-restart into an already-torn-down host.
    Console.Error.WriteLine("AgentBridge stopped.");
    return 0;
}

// ─────────────────────────────────────────────────────────────────────
// HELPERS
// ─────────────────────────────────────────────────────────────────────

// True when the exception chain is a socket bind conflict (port already in use).
// Kestrel wraps the SocketException in AddressInUseException (itself an IOException).
static bool IsAddressInUse(Exception ex)
{
    for (var e = ex; e != null; e = e.InnerException)
        if (e is Microsoft.AspNetCore.Connections.AddressInUseException)
            return true;
    return false;
}

// The locale-neutral AgentResultCode / FailureReason → localized phrase mapping lives in
// AgentResultDisplay (shared with the OfficeManager employee bubbles) so the wording is a
// single source of truth across every chat surface. Call sites use
//   result.Message ?? AgentResultDisplay.ResultText(result) ?? Dictionary.NoOutputGenerated

// Extracts plain text from an OpenAI message content field: a plain string, or the
// structured content array (text / image_url parts) some clients send. image_url parts
// are rendered as "[Image attached]" — the actual image bytes are handled through the
// file_ids / /v1/files flow instead.
static string ExtractTextContent(object? content)
{
    if (content is string text)
        return text;
    if (content is JsonElement json)
    {
        if (json.ValueKind == JsonValueKind.String)
            return json.GetString() ?? "";
        if (json.ValueKind == JsonValueKind.Array)
        {
            var parts = new List<string>();
            foreach (var item in json.EnumerateArray())
            {
                if (item.TryGetProperty("type", out var type))
                {
                    if (type.GetString() == "text" && item.TryGetProperty("text", out var txt))
                        parts.Add(txt.GetString() ?? "");
                    else if (type.GetString() == "image_url")
                        parts.Add("[Image attached]");
                }
            }
            return string.Join("\n", parts);
        }
    }
    return content?.ToString() ?? "";
}

// Maps the OpenAI "model" name to the real agent tool names in AIOrchestrator
// (see AIOrchestrator/docs-dev/ARCHITECTURE.md — "Agent Architecture"): each "model" id exposed
// by /v1/models corresponds to a concrete set of BaseAgentTool names that
// AgentHarness.ExecuteAction resolves to live instances as tools. Shared with the SIP
// telephony loop (AgentTools) so the two paths resolve the same agent sets.
static string[] ResolveAgentTypes(string? model) => AgentTools.Resolve(model);

// A request without session_id that carries PRIOR assistant replies resends the accumulated
// transcript — the precondition for the dynamic-hash correlation (see StatelessConversation.cs).
static bool HasAssistantHistory(List<RequestMessage>? messages) =>
    messages is { Count: > 1 }
    && messages.SkipLast(1).Any(m => m.Role == "assistant" && !string.IsNullOrWhiteSpace(ExtractTextContent(m.Content)));

// The turns of a resent transcript that must become the seeded history: everything BEFORE the
// message used as the prompt (the LAST user message — same rule as the prompt extraction at the
// top of /v1/chat/completions). Excluding the prompt message itself matters when a transcript
// ends with an assistant reply (or with anything but a user turn): taking "everything but the
// last message" would leave the prompt inside the history too, so the LLM would see the same
// question twice.
static IEnumerable<(string Role, string Content)> SeedTurns(List<RequestMessage>? messages)
{
    var promptIndex = messages?.FindLastIndex(m => m.Role == "user") ?? -1;
    for (int i = 0; i < promptIndex; i++)
        yield return (messages![i].Role, ExtractTextContent(messages[i].Content));
}

// Starts a real conversation and seeds it with the transcript the client resends (the earlier
// turns are preserved for the LLM). Used by the stateless dynamic-hash path and when an expired
// session_id is resumed. The session store fires SessionCreated, so OfficeManager spawns the
// persistent employee for the chat.
ActiveSession CreateSeededSession(List<RequestMessage>? messages, string provider)
{
    var s = SessionStore.Create(provider, anonymize);
    s.Orchestrator.SeedHistory(SeedTurns(messages));
    return s;
}

// Resolves the effective LLM provider for a request: the explicit llm_provider field
// (extension) or the appsettings default. Returns null + error message for unknown names.
static string? ResolveProvider(string? requested, string startupProvider, out string? error)
{
    var provider = string.IsNullOrWhiteSpace(requested) ? startupProvider : requested;
    if (!ProviderConfigs.TryGet(provider, out _))
    {
        error = $"Unknown LLM provider '{provider}'. Configured: {string.Join(", ", ProviderConfigs.All.Select(p => p.ProviderName))}.";
        return null;
    }
    error = null;
    return provider;
}

// Context-window guard for the "switch the LLM in use on the fly" operation: estimates
// the conversation tokens (accumulated history + the new prompt) and refuses when they
// exceed the (target) provider's context window. Returns an error payload, or null when
// the conversation fits.
static object? ContextFitError(ActiveSession session, string targetProvider, string newPrompt)
{
    var history = session.Orchestrator.GetHistory();
    return ContextFitErrorFor(EstimateTokens(string.Join("\n", history.Select(h => h.Content)) + "\n" + newPrompt), targetProvider);
}

// The same guard over a raw token estimate: used for the transcript a resumed session is about
// to be seeded with (see the expired-session branch of /v1/chat/completions).
static object? ContextFitErrorFor(int estimate, string targetProvider)
{
    var window = ProviderConfigs.Get(targetProvider).ContextWindow;
    if (estimate <= window) return null;

    return new
    {
        error = "context_window_exceeded",
        detail = $"The conversation needs ≈{estimate} tokens but provider '{targetProvider}' has a context window of {window} tokens. Reset the conversation (POST /v1/control with reset_history: true) or switch to a provider with a larger context window.",
        estimated_tokens = estimate,
        context_window = window,
        provider = targetProvider
    };
}

// Resolves uploaded file ids to FileAttachment instances (original binary + converted
// Markdown, see AgentHarness.ConvertAttachmentToMarkdown), reusing the server-side
// conversion already performed at upload time. Unknown ids are skipped; returns null
// when no usable attachment remains.
//
// This is the "reference later" half of the Files API pattern: the chat request carries
// only the lightweight `file_ids` (OpenAI convention), never the document bytes. The
// original filename survives the round trip because it was stored on CachedFile at upload
// time — the LLM sees it later via the "[File: {FileName}]" header that
// AgentHarness.BuildAttachmentsContext prepends to each Markdown block.
static IEnumerable<FileAttachment>? ResolveAttachments(List<string>? fileIds)
{
    if (fileIds == null || fileIds.Count == 0)
        return null;
    var attachments = new List<FileAttachment>();
    foreach (var fileId in fileIds)
    {
        var cached = FileCache.Get(fileId);
        if (cached == null)
            continue;
        var attachment = new FileAttachment(cached.FileName, cached.Content)
        {
            MarkdownContent = cached.ExtractedText.Length > 0 ? cached.ExtractedText : null
        };
        attachments.Add(attachment);
    }
    return attachments.Count > 0 ? attachments : null;
}

// Rough token estimate (~4 chars per token for latin scripts).
static int EstimateTokens(string text) => (int)Math.Ceiling(text.Length / 4.0);

/// <summary>
/// The `usage` object of an OpenAI-compatible response: the provider's own token counts when it
/// reported them, otherwise the local character estimate — labelled either way, so a client never
/// mistakes one measurement for the other. `prompt_tokens_details.cached_tokens` is OpenAI's place
/// for the part of the prompt served from the provider's prefix cache, and `calls` is our additive
/// field for how many provider calls the turn took (an agent turn is usually several).
/// </summary>
static object UsagePayload(AgentResult result, string prompt, string content) =>
    result.Usage is { Reported: true } u
        ? UsageJson(u)
        : new
        {
            prompt_tokens = EstimateTokens(prompt),
            completion_tokens = EstimateTokens(content),
            total_tokens = EstimateTokens(prompt + content),
            estimated = true,
        };

/// <summary>One <see cref="AgentUsage"/> snapshot in the OpenAI shape (plus our additive
/// `calls`), for the endpoints that report usage without an AgentResult at hand.</summary>
static object UsageJson(AgentUsage usage) => new
{
    prompt_tokens = usage.PromptTokens,
    completion_tokens = usage.CompletionTokens,
    total_tokens = usage.TotalTokens,
    prompt_tokens_details = usage.CachedTokens > 0 ? (object)new { cached_tokens = usage.CachedTokens } : null,
    calls = usage.Calls,
    estimated = false,
};

// JSON-RPC 2.0 helpers for the MCP endpoint. Notifications (missing id) intentionally
// return 204 with no payload, as expected by JSON-RPC.
static IResult McpOk(JsonElement id, bool hasId, object result)
{
    if (!hasId) return Results.NoContent();
    return Results.Json(new { jsonrpc = "2.0", id, result });
}

static IResult McpError(JsonElement id, bool hasId, int code, string message)
{
    if (!hasId) return Results.NoContent();
    return Results.Json(new
    {
        jsonrpc = "2.0",
        id,
        error = new { code, message }
    });
}

static IResult McpToolError(JsonElement id, bool hasId, string message)
{
    if (!hasId) return Results.NoContent();
    return Results.Json(new
    {
        jsonrpc = "2.0",
        id,
        result = new
        {
            content = new[] { new { type = "text", text = message } },
            isError = true
        }
    });
}

// Lightweight JSON argument helpers used by /mcp tools/call.
static string? JsonString(JsonElement obj, string name)
{
    if (obj.ValueKind != JsonValueKind.Object) return null;
    if (!obj.TryGetProperty(name, out var p) || p.ValueKind != JsonValueKind.String) return null;
    return p.GetString();
}

static int? JsonInt(JsonElement obj, string name)
{
    if (obj.ValueKind != JsonValueKind.Object) return null;
    if (!obj.TryGetProperty(name, out var p)) return null;
    if (p.ValueKind == JsonValueKind.Number && p.TryGetInt32(out var n)) return n;
    return null;
}

// Platform capabilities (TTS/voice availability, LLM providers) — GET /v1/control
// without a session and the capabilities block of session states.
object BuildCapabilities()
{
    var ttsAvailable = TtsEngine.IsAvailable;
    return new
    {
        platform = OperatingSystem.IsWindows() ? "windows" : OperatingSystem.IsMacOS() ? "macos" : OperatingSystem.IsLinux() ? "linux" : "other",
        default_provider = startupProvider,
        providers = ProviderConfigs.All.Select(p => new
        {
            name = p.ProviderName,
            model_name = p.ModelName,
            protocol = p.Protocol.ToString(),
            context_window = p.ContextWindow,
            base_address = p.BaseAddress.ToString(),
            interaction_mode = p.EffectiveAgentInteractionMode.ToString()
        }),
        tts = new
        {
            available = ttsAvailable,
            engine = "kokoro",
            voices = TtsEngine.Voices,
            detail = ttsAvailable ? "" : TtsEngine.UnavailableReason
        },
        voice = new
        {
            available = VoiceBridge.IsAvailable,
            engine = "voiceagent-win",
            detail = VoiceBridge.IsAvailable ? "" : VoiceBridge.UnavailableReason
        },
        sip = new
        {
            available = SipBridge.IsEnabled,
            listening = SipBridge.IsListening,
            status = SipBridge.Status
        },
        sessions = SessionStore.Count,
        // Clients whose prompt supports ghost text read this flag; when off they never ask
        // /v1/suggest, so the feature costs nothing anywhere else.
        prompt_suggestion = AIOrchestrator.Setup.PromptSuggestion,
        // Runtime data payload readiness (voices/kokoro.onnx/Lingua models ship in the
        // release archive). Additive: older installs missing a payload report it here so
        // the TUI/web can explain the state in human terms instead of showing errors.
        assets = new
        {
            complete = RuntimeAssets.IsComplete,
            missing = RuntimeAssets.Missing
        }
    };
}

// Full session state for /v1/control responses: the LLM currently in use with its
// characteristics and history estimate, the feature flags, and platform capabilities.
object SessionState(ActiveSession session)
{
    var history = session.Orchestrator.GetHistory();
    return new
    {
        session_id = session.Id,
        llm = new
        {
            provider = session.Orchestrator.Provider,
            model_name = session.Orchestrator.ModelName,
            context_window = session.Orchestrator.ContextWindow,
            interaction_mode = session.Orchestrator.InteractionMode.ToString(),
            history_messages = history.Count,
            history_tokens_estimate = EstimateTokens(string.Join("\n", history.Select(h => h.Content)))
        },
        // Token consumption, as the provider reported it: the turn that just finished and the
        // session total. `estimated: false` marks a real measurement; an estimate (the local
        // character heuristic) is what a provider that reports nothing falls back to.
        usage = new
        {
            last_turn = UsageJson(session.Orchestrator.LastUsage),
            session = UsageJson(session.Usage)
        },
        features = session.Features,
        capabilities = BuildCapabilities()
    };
}

// ─────────────────────────────────────────────────────────────────────
// PUPPET MODE TCP HANDLER — debug-only: injects keyboard/mouse events and
// returns screen captures over localhost:5292. All work is marshalled onto
// the Terminal.Gui main loop by PuppetMode (Tui.cs). One JSON command per
// connection, read until EOF:
//   {"type":"capture"}                                  → current screen as text
//   {"type":"key","key":"<name>"}                       → key press (enter, f10, ctrl+c, ...)
//   {"type":"text","text":"<string>"}                   → text typed character by character
//   {"type":"mouse","x":N,"y":N,"flags":"<name>"}       → mouse click (LeftButtonClicked, ...)
// ─────────────────────────────────────────────────────────────────────
#if DEBUG
static async Task HandlePuppetClientAsync(System.Net.Sockets.TcpClient client, CancellationToken ct)
{
    try
    {
        using var stream = client.GetStream();
        using var reader = new StreamReader(stream);
        var body = await reader.ReadToEndAsync(ct);
        string result;
        if (string.IsNullOrWhiteSpace(body))
            result = "{\"error\":\"empty body\"}";
        else
        {
            using var doc = JsonDocument.Parse(body);
            var root = doc.RootElement;
            var type = root.GetProperty("type").GetString()?.ToLowerInvariant() ?? "";
            Log.LogStep($"Puppet cmd: {type}");
            result = type switch
            {
                "capture" => root.TryGetProperty("grid", out var g) && g.ValueKind == JsonValueKind.True
                    ? GridCapture(PuppetMode.ANSI_Tui_Capture())
                    : PuppetMode.ANSI_Tui_Capture(),
                "hit" => root.TryGetProperty("x", out var hx) && root.TryGetProperty("y", out var hy)
                    ? PuppetMode.HitTest(hx.GetInt32(), hy.GetInt32())
                    : "{\"error\":\"x and y required\"}",
                "key" => HandlePuppetKey(root),
                "text" => HandlePuppetText(root),
                "mouse" => HandlePuppetMouse(root),
                _ => $"{{\"error\":\"unknown type: {type}\"}}",
            };
            Log.LogStep($"Puppet resp({type}): {(result.Length > 120 ? result[..120] + "…" : result)}");
        }
        var response = System.Text.Encoding.UTF8.GetBytes(result);
        await stream.WriteAsync(response, ct);
    }
    catch (Exception ex)
    {
        try
        {
            Log.LogStep($"Puppet error: {ex.Message}");
            var error = System.Text.Encoding.UTF8.GetBytes($"{{\"error\":\"{EscapeJson(ex.Message)}\"}}");
            await client.GetStream().WriteAsync(error, ct);
        }
        catch { }
    }
    finally
    {
        client.Close();
    }
}

static string HandlePuppetKey(JsonElement root)
{
    try
    {
        var name = root.GetProperty("key").GetString() ?? "";
        if (!TryParsePuppetKey(name, out var k))
            return $"{{\"error\":\"unknown key: {name}\"}}";
        PuppetMode.InjectKey(k);
        return "{\"ok\":true}";
    }
    catch (Exception ex) { return $"{{\"error\":\"{EscapeJson(ex.Message)}\"}}"; }
}

static string HandlePuppetText(JsonElement root)
{
    try
    {
        PuppetMode.InjectText(root.GetProperty("text").GetString() ?? "");
        return "{\"ok\":true}";
    }
    catch (Exception ex) { return $"{{\"error\":\"{EscapeJson(ex.Message)}\"}}"; }
}

static string HandlePuppetMouse(JsonElement root)
{
    try
    {
        var x = root.GetProperty("x").GetInt32();
        var y = root.GetProperty("y").GetInt32();
        var flagsStr = root.GetProperty("flags").GetString() ?? "LeftButtonClicked";
        if (!Enum.TryParse<MouseFlags>(flagsStr, out var flags))
            return $"{{\"error\":\"unknown flags: {flagsStr}\"}}";
        PuppetMode.InjectMouse(x, y, flags);
        return "{\"ok\":true}";
    }
    catch (Exception ex) { return $"{{\"error\":\"{EscapeJson(ex.Message)}\"}}"; }
}

// Documented key names first (deterministic), then fall back to Key.TryParse
// for free-form forms like "ctrl+o", "alt+enter", "ctrl+shift+a".
static bool TryParsePuppetKey(string name, out Key key)
{
    switch (name.ToLowerInvariant())
    {
        case "enter": key = Key.Enter; return true;
        case "escape" or "esc": key = Key.Esc; return true;
        case "tab": key = Key.Tab; return true;
        case "backspace": key = Key.Backspace; return true;
        case "delete" or "del": key = Key.Delete; return true;
        case "space": key = Key.Space; return true;
        case "printscreen": key = Key.PrintScreen; return true;
        case "cursorup" or "up": key = Key.CursorUp; return true;
        case "cursordown" or "down": key = Key.CursorDown; return true;
        case "cursorleft" or "left": key = Key.CursorLeft; return true;
        case "cursorright" or "right": key = Key.CursorRight; return true;
        case "pageup" or "pgup": key = Key.PageUp; return true;
        case "pagedown" or "pgdn": key = Key.PageDown; return true;
        case "home": key = Key.Home; return true;
        case "end": key = Key.End; return true;
        case "f1": key = Key.F1; return true;
        case "f2": key = Key.F2; return true;
        case "f3": key = Key.F3; return true;
        case "f4": key = Key.F4; return true;
        case "f5": key = Key.F5; return true;
        case "f6": key = Key.F6; return true;
        case "f7": key = Key.F7; return true;
        case "f8": key = Key.F8; return true;
        case "f9": key = Key.F9; return true;
        case "f10": key = Key.F10; return true;
        case "f11": key = Key.F11; return true;
        case "f12": key = Key.F12; return true;
    }
    return Key.TryParse(name, out key);
}

static string EscapeJson(string text) =>
    text.Replace("\\", "\\\\").Replace("\"", "\\\"").Replace("\r", " ").Replace("\n", " ");

// Adds a coordinate grid to the capture so mouse coordinates can be read exactly:
// two header rows (column tens + units) and each screen row prefixed with its
// 0-based row number. Mouse x/y in {"type":"mouse"} map directly to these cells.
static string GridCapture(string text)
{
    var lines = text.TrimEnd('\n').Split('\n');
    var width = lines.Max(l => l.Length);
    var sb = new StringBuilder();
    var tens = "     ";
    var units = "     ";
    for (int c = 0; c < width; c++)
    {
        tens += c % 100 / 10 == 0 && c % 10 == 0 ? ((c / 100) % 10).ToString() : (c % 10 == 0 ? ((c / 10) % 10).ToString() : " ");
        units += (c % 10).ToString();
    }
    sb.AppendLine(tens);
    sb.AppendLine(units);
    for (int r = 0; r < lines.Length; r++)
        sb.AppendLine($"{r:D4} {lines[r]}");
    return sb.ToString();
}
#endif

// A result for a response whose body the handler already wrote to the stream. Results.Stream
// cannot be used there: its delegate runs only after the handler returns, which would let the
// handler's finally dispose the agent harness mid-run. This result writes nothing and touches
// no response header, so it is safe after the body has started.
internal sealed class ResponseAlreadyWritten : IResult
{
    public Task ExecuteAsync(HttpContext context) => Task.CompletedTask;
}