Only the delta.

1
2
3
4

<Project>
  <!-- V5 scheduling development. V4 alpha is preserved separately. -->
  <PropertyGroup><VersionPrefix>5.0.0</VersionPrefix><VersionSuffix>alpha.2</VersionSuffix></PropertyGroup>
</Project>

1
2
3
4

<Project>
  <!-- V4 workspace development. V3 alpha is preserved separately. -->
  <PropertyGroup><VersionPrefix>4.0.0</VersionPrefix><VersionSuffix>alpha.3</VersionSuffix></PropertyGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

using System;
using System.Text;
using System.Threading.Tasks;
using Lilith.Core.Logging;
using Lilith.Agent;
using LilithAgent = Lilith.Agent;
using LilithConsole.Setup;
using Lilith.Core.Kokoro;

namespace LilithConsole
{
    partial class Program
    {
        static async Task Main(string[] args)
        {
            Console.OutputEncoding = Encoding.UTF8;
            var consoleSink = new TextLogSink(Console.Out, overwriteProgress: !Console.IsOutputRedirected,
                width: () => Math.Max(Console.WindowWidth - 1, 1));
            Action<LogEntry> onLog = consoleSink.Handle;

            var logger = new Logger(onLog);
            try
            {
                string settingsPath = Environment.GetEnvironmentVariable("LILITH_CONSOLE_SETTINGS")
                    ?? System.IO.Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Lilith", "console-settings.json");
                var credentials = await ProviderSetup.RunAsync(Console.In, Console.Out, logger, settingsPath);
                if (credentials is null) { logger.SystemWriteLine("Setup stopped. Relaunch to continue."); return; }
                if (!Console.IsInputRedirected || Environment.GetEnvironmentVariable("LILITH_TTS") == "1")
                {
                    try
                    {
                        credentials = credentials with { Tts = await KokoroSetup.RunAsync(Console.In, Console.Out,
                            logger, settingsPath + ".kokoro.json") };
                    }
                    catch (Exception ex) { logger.SystemWriteLine($"Speech setup failed: {ex.Message}. Relaunch to retry; continuing with text chat.", LogColors.Orange); }
                }
                Console.Title = $"{credentials.AgentName} — {credentials.Model} Chat";
                await using var lilith = new LilithAgent.Lilith(onLog, credentials);
                string mode = "ask";
                if (!Console.IsInputRedirected)
                {
                    Console.Write("Workspace and scheduling mode for this boot [ask/yolo, default ask]: ");
                    mode = Console.ReadLine()?.Trim().ToLowerInvariant() ?? "ask";
                    if (mode.Length == 0) mode = "ask";
                    if (mode is not ("ask" or "yolo")) throw new ArgumentException("Choose ask or yolo at boot.");
                }
                else if (args.Contains("--workspace-yolo")) mode = "yolo";
                var workspace = Lilith.Core.Workspace.WorkspaceOptions.Default;
                string? workspaceRoot = Environment.GetEnvironmentVariable("LILITH_WORKSPACE_ROOT");
                lilith.WorkspaceOptions = workspace with { RootDirectory = workspaceRoot ?? workspace.RootDirectory,
                    Mode = mode == "yolo" ? Lilith.Core.Workspace.WorkspaceAccessMode.Yolo : Lilith.Core.Workspace.WorkspaceAccessMode.Ask };
                Console.WriteLine($"Workspace: {lilith.WorkspaceOptions.RootDirectory} ({mode}, fixed until restart). Use /workspace, /workspace review <id>, /approve <id>, /reject <id>.");
                await lilith.BootAsync(startServerIfNotRunning: true);

                while (true)
                {
                    string? input;
                    using (consoleSink.BeginInput())
                    {
                        lilith.Logger.Write("Input", "You: ", LogColors.Green);
                        input = Console.ReadLine()?.Trim();
                    }
                    if (input is null) break;
                    if (string.IsNullOrEmpty(input)) continue;
                    if (input.Equals("exit", StringComparison.OrdinalIgnoreCase)) break;
                    try
                    {
                        var command = await lilith.ChatCommands.ExecuteAsync(input);
                        if (command.Output is { Length: > 0 }) Console.WriteLine(command.Output);
                        if (command.ExitRequested) break;
                        if (!command.Handled) await lilith.ChatAsync(input);
                    }
                    catch (Exception ex)
                    {
                        lilith.Logger.SystemWriteLine($"Request failed: {ex.Message}. Please try again.", LogColors.Red);
                    }
                }
                await lilith.StopSchedulingAsync();
                lilith.SaveConversation();
                lilith.Logger.SystemWriteLine("Goodbye.");
            }
            catch (Exception ex)
            {
                logger.SystemWriteLine($"Setup/chat failed: {ex.Message}. Relaunch to retry; completed setup steps are retained.", LogColors.Red);
                Environment.ExitCode = 1;
            }
            finally { consoleSink.Flush(); }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

using System;
using System.Text;
using System.Threading.Tasks;
using Lilith.Core.Logging;
using Lilith.Agent;
using LilithAgent = Lilith.Agent;
using LilithConsole.Setup;
using Lilith.Core.Kokoro;

namespace LilithConsole
{
    partial class Program
    {
        static async Task Main(string[] args)
        {
            Console.OutputEncoding = Encoding.UTF8;
            var consoleSink = new TextLogSink(Console.Out, overwriteProgress: !Console.IsOutputRedirected,
                width: () => Math.Max(Console.WindowWidth - 1, 1));
            Action<LogEntry> onLog = consoleSink.Handle;

            var logger = new Logger(onLog);
            try
            {
                string settingsPath = Environment.GetEnvironmentVariable("LILITH_CONSOLE_SETTINGS")
                    ?? System.IO.Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Lilith", "console-settings.json");
                var credentials = await ProviderSetup.RunAsync(Console.In, Console.Out, logger, settingsPath);
                if (credentials is null) { logger.SystemWriteLine("Setup stopped. Relaunch to continue."); return; }
                if (!Console.IsInputRedirected || Environment.GetEnvironmentVariable("LILITH_TTS") == "1")
                {
                    try
                    {
                        credentials = credentials with { Tts = await KokoroSetup.RunAsync(Console.In, Console.Out,
                            logger, settingsPath + ".kokoro.json") };
                    }
                    catch (Exception ex) { logger.SystemWriteLine($"Speech setup failed: {ex.Message}. Relaunch to retry; continuing with text chat.", LogColors.Orange); }
                }
                Console.Title = $"{credentials.AgentName} — {credentials.Model} Chat";
                await using var lilith = new LilithAgent.Lilith(onLog, credentials);
                string mode = "ask";
                if (!Console.IsInputRedirected)
                {
                    Console.Write("Workspace mode for this boot [ask/yolo, default ask]: ");
                    mode = Console.ReadLine()?.Trim().ToLowerInvariant() ?? "ask";
                    if (mode.Length == 0) mode = "ask";
                    if (mode is not ("ask" or "yolo")) throw new ArgumentException("Choose ask or yolo at boot.");
                }
                else if (args.Contains("--workspace-yolo")) mode = "yolo";
                var workspace = Lilith.Core.Workspace.WorkspaceOptions.Default;
                string? workspaceRoot = Environment.GetEnvironmentVariable("LILITH_WORKSPACE_ROOT");
                lilith.WorkspaceOptions = workspace with { RootDirectory = workspaceRoot ?? workspace.RootDirectory,
                    Mode = mode == "yolo" ? Lilith.Core.Workspace.WorkspaceAccessMode.Yolo : Lilith.Core.Workspace.WorkspaceAccessMode.Ask };
                Console.WriteLine($"Workspace: {lilith.WorkspaceOptions.RootDirectory} ({mode}, fixed until restart). Use /workspace, /workspace review <id>, /approve <id>, /reject <id>.");
                await lilith.BootAsync(startServerIfNotRunning: true);

                while (true)
                {
                    string? input;
                    using (consoleSink.BeginInput())
                    {
                        lilith.Logger.Write("Input", "You: ", LogColors.Green);
                        input = Console.ReadLine()?.Trim();
                    }
                    if (input is null) break;
                    if (string.IsNullOrEmpty(input)) continue;
                    if (input.Equals("exit", StringComparison.OrdinalIgnoreCase)) break;
                    try
                    {
                        var command = await lilith.ChatCommands.ExecuteAsync(input);
                        if (command.Output is { Length: > 0 }) Console.WriteLine(command.Output);
                        if (command.ExitRequested) break;
                        if (!command.Handled) await lilith.ChatAsync(input);
                    }
                    catch (Exception ex)
                    {
                        lilith.Logger.SystemWriteLine($"Request failed: {ex.Message}. Please try again.", LogColors.Red);
                    }
                }
                lilith.SaveConversation();
                lilith.Logger.SystemWriteLine("Goodbye.");
            }
            catch (Exception ex)
            {
                logger.SystemWriteLine($"Setup/chat failed: {ex.Message}. Relaunch to retry; completed setup steps are retained.", LogColors.Red);
                Environment.ExitCode = 1;
            }
            finally { consoleSink.Flush(); }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

using Lilith.Core.Logging;
using Lilith.Core.Ollama;

namespace Lilith.Agent;

public partial class Lilith
{
    public bool IsBooted { get; private set; }

    public async Task BootAsync(bool startServerIfNotRunning = true)
    {
        using var operation = EnterOperation();
        try
        {
            if (IsBooted) return;
            if (string.IsNullOrWhiteSpace(Credentials.Model) || string.IsNullOrWhiteSpace(Credentials.SystemPrompt) ||
                string.IsNullOrWhiteSpace(Credentials.AgentName)) throw new ArgumentException("Model, system prompt, and agent name are required.");
            await Logger.TimeStageAsync("Total agent boot", () => BootCoreAsync(startServerIfNotRunning));
        }
        catch
        {
            _llmclient?.Dispose();
            _llmclient = null!;
            IsBooted = false;
            throw;
        }
    }

    private async Task BootCoreAsync(bool startServerIfNotRunning)
    {
        IsBooted = false;
        await Logger.TimeStageAsync("Client initialization", () => InitializeProviderAsync(startServerIfNotRunning));
        await Logger.TimeStageAsync("Chat readiness validation", () => { EnsureChatReadiness(); return Task.CompletedTask; });
        if (Credentials.Tts is { Enabled: true } options && _tts is null)
        {
            try
            {
                _tts = await Logger.TimeStageAsync("Kokoro initialization", () =>
                    global::Lilith.Core.Kokoro.KokoroTts.CreateAsync(Logger, options));
            }
            catch (Exception ex) { Logger.SystemWriteLine($"Speech unavailable: {ex.Message}. Text chat remains available.", LogColors.Orange); }
        }
        Logger.SystemWriteLine($"=== {Credentials.AgentName} AI Chat ({Credentials.Model} via {Credentials.Provider}) ===");
        Logger.SystemWriteLine("Type your message and press Enter. Type 'exit' to quit.\n");
        Logger.SystemPromptWriteLine($"SYSTEM: {Credentials.SystemPrompt}");
        await Logger.TimeStageAsync("Greeting generation", GreetingCoreAsync);
        Logger.SystemWriteLine("", LogColors.White);
        IsBooted = true;
        if (EnableScenarios) _schedulePump = Task.WhenAll(DetectSchedulesAsync(_scheduleStop.Token), PumpSchedulesAsync(_scheduleStop.Token));
    }

    public async Task GreetAsync()
    {
        using var operation = EnterOperation("Boot the agent before greeting.");
        await GreetingCoreAsync();
    }

    private async Task GreetingCoreAsync()
    {
        if (!EnableScenarios)
        {
            await ChatCoreAsync("Please greet the user.");
            return;
        }
        string greeting = await Client.RunScenarioAsync("greeting", new Dictionary<string, string>
        {
            ["agent_name"] = Credentials.AgentName
        });
        if (_tts is not null) await _tts.SpeakAsync(greeting);
    }

    private void EnsureChatReadiness()
    {
        _llmclient.IsNull();
        this.EnsureSystemPromptContent();
        this.EnsureContextInitialized();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

using Lilith.Core.Logging;
using Lilith.Core.Ollama;

namespace Lilith.Agent;

public partial class Lilith
{
    public bool IsBooted { get; private set; }

    public async Task BootAsync(bool startServerIfNotRunning = true)
    {
        using var operation = EnterOperation();
        try
        {
            if (IsBooted) return;
            if (string.IsNullOrWhiteSpace(Credentials.Model) || string.IsNullOrWhiteSpace(Credentials.SystemPrompt) ||
                string.IsNullOrWhiteSpace(Credentials.AgentName)) throw new ArgumentException("Model, system prompt, and agent name are required.");
            await Logger.TimeStageAsync("Total agent boot", () => BootCoreAsync(startServerIfNotRunning));
        }
        catch
        {
            _llmclient?.Dispose();
            _llmclient = null!;
            IsBooted = false;
            throw;
        }
    }

    private async Task BootCoreAsync(bool startServerIfNotRunning)
    {
        IsBooted = false;
        await Logger.TimeStageAsync("Client initialization", () => InitializeProviderAsync(startServerIfNotRunning));
        await Logger.TimeStageAsync("Chat readiness validation", () => { EnsureChatReadiness(); return Task.CompletedTask; });
        if (Credentials.Tts is { Enabled: true } options && _tts is null)
        {
            try
            {
                _tts = await Logger.TimeStageAsync("Kokoro initialization", () =>
                    global::Lilith.Core.Kokoro.KokoroTts.CreateAsync(Logger, options));
            }
            catch (Exception ex) { Logger.SystemWriteLine($"Speech unavailable: {ex.Message}. Text chat remains available.", LogColors.Orange); }
        }
        Logger.SystemWriteLine($"=== {Credentials.AgentName} AI Chat ({Credentials.Model} via {Credentials.Provider}) ===");
        Logger.SystemWriteLine("Type your message and press Enter. Type 'exit' to quit.\n");
        Logger.SystemPromptWriteLine($"SYSTEM: {Credentials.SystemPrompt}");
        await Logger.TimeStageAsync("Greeting generation", GreetingCoreAsync);
        Logger.SystemWriteLine("", LogColors.White);
        IsBooted = true;
    }

    public async Task GreetAsync()
    {
        using var operation = EnterOperation("Boot the agent before greeting.");
        await GreetingCoreAsync();
    }

    private async Task GreetingCoreAsync()
    {
        if (!EnableScenarios)
        {
            await ChatCoreAsync("Please greet the user.");
            return;
        }
        string greeting = await Client.RunScenarioAsync("greeting", new Dictionary<string, string>
        {
            ["agent_name"] = Credentials.AgentName
        });
        if (_tts is not null) await _tts.SpeakAsync(greeting);
    }

    private void EnsureChatReadiness()
    {
        _llmclient.IsNull();
        this.EnsureSystemPromptContent();
        this.EnsureContextInitialized();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using System.Diagnostics;

namespace Lilith.Agent;

public partial class Lilith
{
    public async Task ChatAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = await _operation.EnterAsync(cancellationToken);
        ObjectDisposedException.ThrowIf(_disposed, this);
        if (!IsBooted) throw new InvalidOperationException("Boot the agent before chatting.");
        await ChatCoreAsync(input, images, cancellationToken);
    }

    private async Task ChatCoreAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        var timer = Stopwatch.StartNew();
        string reply;
        try { reply = await Client.StreamReply(input, images, cancellationToken); }
        finally { timer.Stop(); }
        this.LogTokenCounts(timer.Elapsed);
        if (_tts is not null) await _tts.SpeakAsync(reply, cancellationToken);
    }

    private T WithConversation<T>(Func<ProviderClient, T> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        return action(Client);
    }

    private void WithConversation(Action<ProviderClient> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        action(Client);
    }

    public void NewConversation() => WithConversation(client => client.NewConversation());
    public async Task ApproveWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot before approving workspace changes.");
        string reply = await Client.ApproveWorkspaceAsync(id, cancellationToken);
        if (_tts is not null) await _tts.SpeakAsync(reply, cancellationToken);
    }
    public async Task RejectWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot before rejecting workspace changes.");
        var result = await Workspace.ExecuteAsync(new("reject", BinId: id), cancellationToken);
        Logger.SystemWriteLine(result.Message);
    }

    public void SaveConversation() => WithConversation(client => client.SaveConversation());

    public IReadOnlyList<ChatSessionSummary> ListConversations() => WithConversation(client => client.ListConversations());

    public bool LoadConversation(int displayIndex) => WithConversation(client => client.LoadConversation(displayIndex));

    public bool LoadConversation(string id) => WithConversation(client => client.LoadConversation(id));

    public void HandleHistoryCommand(string input)
    {
        var parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (parts.Length == 1)
        {
            var sessions = ListConversations();
            if (sessions.Count == 0)
            {
                Logger.HistoryWriteLine("No saved chats found.");
                return;
            }

            Logger.HistoryWriteLine("Saved chats:", LogColors.Cyan);
            for (int i = 0; i < sessions.Count; i++)
            {
                var session = sessions[i];
                Logger.HistoryWriteLine($"{i + 1}. {session.Title} ({session.UpdatedAt.LocalDateTime:g}, {session.MessageCount} messages)");
            }

            Logger.HistoryWriteLine("Use /history <number> to load a chat.");
            return;
        }

        if (!int.TryParse(parts[1], out int index))
        {
            Logger.HistoryWriteLine("Usage: /history or /history <number>", LogColors.Orange);
            return;
        }

        if (LoadConversation(index))
        {
            Logger.HistoryWriteLine($"Loaded saved chat #{index}.", LogColors.Cyan);
        }
        else
        {
            Logger.HistoryWriteLine($"Saved chat #{index} was not found.", LogColors.Orange);
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using System.Diagnostics;

namespace Lilith.Agent;

public partial class Lilith
{
    public async Task ChatAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot the agent before chatting.");
        await ChatCoreAsync(input, images, cancellationToken);
    }

    private async Task ChatCoreAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        var timer = Stopwatch.StartNew();
        string reply;
        try { reply = await Client.StreamReply(input, images, cancellationToken); }
        finally { timer.Stop(); }
        this.LogTokenCounts(timer.Elapsed);
        if (_tts is not null) await _tts.SpeakAsync(reply, cancellationToken);
    }

    private T WithConversation<T>(Func<ProviderClient, T> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        return action(Client);
    }

    private void WithConversation(Action<ProviderClient> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        action(Client);
    }

    public void NewConversation() => WithConversation(client => client.NewConversation());
    public async Task ApproveWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot before approving workspace changes.");
        string reply = await Client.ApproveWorkspaceAsync(id, cancellationToken);
        if (_tts is not null) await _tts.SpeakAsync(reply, cancellationToken);
    }
    public async Task RejectWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot before rejecting workspace changes.");
        var result = await Workspace.ExecuteAsync(new("reject", BinId: id), cancellationToken);
        Logger.SystemWriteLine(result.Message);
    }

    public void SaveConversation() => WithConversation(client => client.SaveConversation());

    public IReadOnlyList<ChatSessionSummary> ListConversations() => WithConversation(client => client.ListConversations());

    public bool LoadConversation(int displayIndex) => WithConversation(client => client.LoadConversation(displayIndex));

    public bool LoadConversation(string id) => WithConversation(client => client.LoadConversation(id));

    public void HandleHistoryCommand(string input)
    {
        var parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (parts.Length == 1)
        {
            var sessions = ListConversations();
            if (sessions.Count == 0)
            {
                Logger.HistoryWriteLine("No saved chats found.");
                return;
            }

            Logger.HistoryWriteLine("Saved chats:", LogColors.Cyan);
            for (int i = 0; i < sessions.Count; i++)
            {
                var session = sessions[i];
                Logger.HistoryWriteLine($"{i + 1}. {session.Title} ({session.UpdatedAt.LocalDateTime:g}, {session.MessageCount} messages)");
            }

            Logger.HistoryWriteLine("Use /history <number> to load a chat.");
            return;
        }

        if (!int.TryParse(parts[1], out int index))
        {
            Logger.HistoryWriteLine("Usage: /history or /history <number>", LogColors.Orange);
            return;
        }

        if (LoadConversation(index))
        {
            Logger.HistoryWriteLine($"Loaded saved chat #{index}.", LogColors.Cyan);
        }
        else
        {
            Logger.HistoryWriteLine($"Saved chat #{index} was not found.", LogColors.Orange);
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

using System.Text.Json;
using Lilith.Core.Commands;

namespace Lilith.Agent;

public partial class Lilith
{
    partial void RegisterScheduleCommands(ChatCommandRegistry commands)
    {
        commands.Register("schedules", "List schedules; use pending or review <id> for proposals.", context => context.Arguments switch
        {
            "" => JsonSerializer.Serialize(Schedules.Execute(new("list"))),
            "pending" => JsonSerializer.Serialize(Schedules.Execute(new("pending"))),
            var args when args.StartsWith("review ", StringComparison.OrdinalIgnoreCase) => JsonSerializer.Serialize(Schedules.Review(args[7..].Trim()), new JsonSerializerOptions { WriteIndented = true }),
            _ => "Use /schedules, /schedules pending or /schedules review <id>."
        });
        commands.RegisterAsync("schedule-approve", "Approve a schedule proposal: /schedule-approve <id>.", async context => { await ApproveScheduleAsync(context.Arguments, context.CancellationToken); return new(true); });
        commands.Register("schedule-reject", "Reject a schedule proposal: /schedule-reject <id>.", context => { RejectSchedule(context.Arguments); return null; });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

namespace Lilith.Agent;

public partial class Lilith
{
    public async Task StopSchedulingAsync()
    {
        _scheduleStop.Cancel();
        if (_schedulePump is not null) await _schedulePump;
    }

    private async Task DetectSchedulesAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(1));
        try
        {
            while (await timer.WaitForNextTickAsync(ct))
                try { Schedules.Tick(); }
                catch (Exception ex) { Logger.SystemWriteLine("Schedule detection failed: " + ex.Message, global::Lilith.Core.Logging.LogColors.Red); }
        }
        catch (OperationCanceledException) when (ct.IsCancellationRequested) { }
    }

    private async Task PumpSchedulesAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(1));
        try
        {
            while (await timer.WaitForNextTickAsync(ct))
            {
                try
                {
                    // Detection runs separately; delivery must own conversation and narration access.
                    if (!await _operation.WaitAsync(0, ct)) continue;
                    try { await DeliverScheduleEventsAsync(ct); }
                    finally { _operation.Release(); }
                }
                catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
                catch (Exception ex) { Logger.SystemWriteLine("Scheduler: " + ex.Message, global::Lilith.Core.Logging.LogColors.Red); }
            }
        }
        catch (OperationCanceledException) when (ct.IsCancellationRequested) { }
    }

    private Task DeliverScheduleEventsAsync(CancellationToken ct) =>
        global::Lilith.Core.Scheduling.ScheduleDelivery.DrainAsync(Client,
            (text, token) => _tts is null ? Task.CompletedTask : _tts.SpeakAsync(text, token), ct);

    public async Task ApproveScheduleAsync(string id, CancellationToken ct = default)
    {
        using var operation = EnterOperation("Boot before approving schedule changes.");
        string reply = Schedules.Approve(id).ToReply();
        Logger.SystemWriteLine(reply);
        if (_tts is not null) await _tts.SpeakAsync(reply, ct);
    }

    public void RejectSchedule(string id)
    {
        using var operation = EnterOperation("Boot before rejecting schedule changes.");
        Schedules.Reject(id);
        Logger.SystemWriteLine("Schedule proposal rejected.");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using Lilith.Core.Kokoro;

namespace Lilith.Agent;

public partial class Lilith(Action<LogEntry> onLog, LilithCredentials? credentials = null) : IAsyncDisposable
{
    private KokoroTts? _tts;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private readonly CancellationTokenSource _scheduleStop = new();
    private Task? _schedulePump;
    private ProviderClient _llmclient = null!;
    private bool _workspaceLocked;
    private global::Lilith.Core.Workspace.WorkspaceOptions _workspaceOptions = global::Lilith.Core.Workspace.WorkspaceOptions.Default;
    public global::Lilith.Core.Workspace.WorkspaceOptions WorkspaceOptions
    {
        get => _workspaceOptions;
        set { if (_workspaceLocked) throw new InvalidOperationException("Workspace configuration can only be chosen before boot."); _workspaceOptions = value ?? throw new ArgumentNullException(nameof(value)); }
    }
    public global::Lilith.Core.Workspace.WorkspaceSession Workspace => Client.Workspace ?? throw new InvalidOperationException("Workspace unavailable.");
    public global::Lilith.Core.Scheduling.ScheduleSession Schedules => Client.Schedules ?? throw new InvalidOperationException("Schedules unavailable.");
    private readonly LilithCredentials _credentials = credentials ?? new();

    public LilithCredentials Credentials => _credentials;
    public Logger Logger { get; } = new(onLog);
    internal Func<bool, Task<ProviderClient>>? ProviderFactory { get; set; }

    private ProviderClient Client
    {
        get
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            return _llmclient ?? throw new InvalidOperationException("Boot the agent before using its conversation.");
        }
    }
    public ChatHistory History => Client.History;
    public int ContextMax => Client.ContextMax;
    public int CurrentContextTokens => Client.CurrentContextTokens;

    private async Task InitializeProviderAsync(bool startServerIfNotRunning)
    {
        _workspaceLocked = true;
        _llmclient = ProviderFactory is { } factory ? await factory(startServerIfNotRunning) : await this.CreateClient(startServerIfNotRunning);
        _llmclient.ShowSubagentOutput = _showSubagentOutput;
        _llmclient.ConfigureWorkspace(_workspaceOptions);
        if (EnableScenarios) _llmclient.ConfigureSchedules(new(Path.Combine(_workspaceOptions.RootDirectory, ".lilith", "schedules"), _workspaceOptions.Mode), ScenarioRoot);
        foreach (var tool in Tools) _llmclient.RegisterTool(tool);
        if (EnableScenarios) global::Lilith.Core.Scenarios.ScenarioTools.Register(_llmclient, ScenarioRoot);
    }

    public bool EnableScenarios { get; set; } = true;
    public string? ScenarioRoot { get; set; }

    /// <summary>Configure before boot. The template is deliberately not enabled.</summary>
    public List<global::Lilith.Core.Tools.ILilithTool> Tools { get; } = [new global::Lilith.Core.Tools.CurrentTimeTool()];

    private IDisposable EnterOperation(string? bootRequiredMessage = null)
    {
        var operation = _operation.EnterOrThrow("An agent operation is already in progress.");
        try
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            if (bootRequiredMessage is not null && !IsBooted) throw new InvalidOperationException(bootRequiredMessage);
            return operation;
        }
        catch { operation.Dispose(); throw; }
    }

    public async ValueTask DisposeAsync()
    {
        await StopSchedulingAsync();
        using var operation = await _operation.EnterAsync();
        if (_disposed) return;
        _disposed = true;
        try { if (_tts is not null) await _tts.DisposeAsync(); }
        finally { _llmclient?.Dispose(); IsBooted = false; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using Lilith.Core.Kokoro;

namespace Lilith.Agent;

public partial class Lilith(Action<LogEntry> onLog, LilithCredentials? credentials = null) : IAsyncDisposable
{
    private KokoroTts? _tts;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private ProviderClient _llmclient = null!;
    private bool _workspaceLocked;
    private global::Lilith.Core.Workspace.WorkspaceOptions _workspaceOptions = global::Lilith.Core.Workspace.WorkspaceOptions.Default;
    public global::Lilith.Core.Workspace.WorkspaceOptions WorkspaceOptions
    {
        get => _workspaceOptions;
        set { if (_workspaceLocked) throw new InvalidOperationException("Workspace configuration can only be chosen before boot."); _workspaceOptions = value ?? throw new ArgumentNullException(nameof(value)); }
    }
    public global::Lilith.Core.Workspace.WorkspaceSession Workspace => Client.Workspace ?? throw new InvalidOperationException("Workspace unavailable.");
    private readonly LilithCredentials _credentials = credentials ?? new();

    public LilithCredentials Credentials => _credentials;
    public Logger Logger { get; } = new(onLog);
    internal Func<bool, Task<ProviderClient>>? ProviderFactory { get; set; }

    private ProviderClient Client
    {
        get
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            return _llmclient ?? throw new InvalidOperationException("Boot the agent before using its conversation.");
        }
    }
    public ChatHistory History => Client.History;
    public int ContextMax => Client.ContextMax;
    public int CurrentContextTokens => Client.CurrentContextTokens;

    private async Task InitializeProviderAsync(bool startServerIfNotRunning)
    {
        _workspaceLocked = true;
        _llmclient = ProviderFactory is { } factory ? await factory(startServerIfNotRunning) : await this.CreateClient(startServerIfNotRunning);
        _llmclient.ShowSubagentOutput = _showSubagentOutput;
        _llmclient.ConfigureWorkspace(_workspaceOptions);
        foreach (var tool in Tools) _llmclient.RegisterTool(tool);
        if (EnableScenarios) global::Lilith.Core.Scenarios.ScenarioTools.Register(_llmclient, ScenarioRoot);
    }

    public bool EnableScenarios { get; set; } = true;
    public string? ScenarioRoot { get; set; }

    /// <summary>Configure before boot. The template is deliberately not enabled.</summary>
    public List<global::Lilith.Core.Tools.ILilithTool> Tools { get; } = [new global::Lilith.Core.Tools.CurrentTimeTool()];

    private IDisposable EnterOperation(string? bootRequiredMessage = null)
    {
        var operation = _operation.EnterOrThrow("An agent operation is already in progress.");
        try
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            if (bootRequiredMessage is not null && !IsBooted) throw new InvalidOperationException(bootRequiredMessage);
            return operation;
        }
        catch { operation.Dispose(); throw; }
    }

    public async ValueTask DisposeAsync()
    {
        using var operation = await _operation.EnterAsync();
        if (_disposed) return;
        _disposed = true;
        try { if (_tts is not null) await _tts.DisposeAsync(); }
        finally { _llmclient?.Dispose(); IsBooted = false; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>Lilith.Core</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Cronos" Version="0.13.0" />
    <PackageReference Include="KokoroSharp.CPU" Version="0.8.4" />
    <Content Include="Scenarios/Definitions/*.xml" Link="Scenarios/%(Filename)%(Extension)" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>Lilith.Core</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="KokoroSharp.CPU" Version="0.8.4" />
    <Content Include="Scenarios/Definitions/*.xml" Link="Scenarios/%(Filename)%(Extension)"
             CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11

using System.Text.RegularExpressions;

namespace Lilith.Core.Kokoro;

internal static class KokoroIdentifiers
{
    private static readonly string[] Digits = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"];
    // Approval/bin hashes are identifiers, not large integers. Keep display/history untouched.
    internal static string Expand(string text) => Regex.Replace(text, @"(?<![A-Za-z0-9])[A-Fa-f0-9]{24,64}(?![A-Za-z0-9])",
        match => string.Join(" ", match.Value.Select(c => c is >= '0' and <= '9' ? Digits[c - '0'] : c.ToString())));
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

using System.Globalization;
using System.Text;

namespace Lilith.Core.Kokoro;

/// <summary>Conservative speech cleanup; leaves pronunciation of numbers/abbreviations to the phonemizer.</summary>
public static class KokoroTtsSanitizer
{
    public static string Sanitize(string text)
    {
        ArgumentNullException.ThrowIfNull(text);
        // Remove fenced code before interpreting its contents as prose, including an unclosed fence.
        text = KokoroRegex.CodeFence().Replace(text, " ");
        text = KokoroRegex.MarkdownLink().Replace(text, "${label}");
        text = KokoroRegex.WebUrl().Replace(text, match =>
        {
            // Discard the address but retain punctuation ending the surrounding sentence.
            string url = match.Value.TrimEnd(')', ']', '}', '"', '\'');
            int end = url.Length;
            while (end > 0 && ".!?;:".Contains(url[end - 1])) end--;
            return " " + url[end..];
        });
        for (int pass = 0; pass < 3; pass++) text = KokoroRegex.Emphasis().Replace(text, "${value}");
        text = KokoroRegex.StrikeThrough().Replace(text, "${value}").Replace("`", "");

        // Misaki can split surrogate pairs before normalization; spoken input excludes pictographs.
        // Grapheme rendering and the original chat/history text remain untouched.
        var spoken = new StringBuilder(text.Length);
        foreach (var rune in text.EnumerateRunes())
        {
            if (rune.Value is 0x200B or 0x2060 or 0xFEFF or 0x00AD) continue;
            bool unsupported = rune.Utf16SequenceLength == 2 || Rune.GetUnicodeCategory(rune) == UnicodeCategory.OtherSymbol ||
                rune.Value is 0x200D or 0xFE0E or 0xFE0F or 0xFFFD ||
                (Rune.GetUnicodeCategory(rune) == UnicodeCategory.Control && rune.Value is not (9 or 10 or 13));
            spoken.Append(unsupported ? " " : rune.ToString());
        }
        text = spoken.ToString().Normalize(NormalizationForm.FormC).Replace("\r\n", "\n").Replace('\r', '\n');
        var result = new StringBuilder(text.Length);
        bool paragraphBreak = false, previousList = false;
        foreach (string raw in text.Split('\n'))
        {
            string line = raw.Trim();
            if (line.Length == 0) { paragraphBreak = result.Length > 0; continue; }
            bool listItem = KokoroRegex.ListMarker().IsMatch(line);
            bool heading = KokoroRegex.HeadingMarker().IsMatch(line);
            line = KokoroRegex.ListMarker().Replace(line, "");
            line = KokoroRegex.HeadingMarker().Replace(line, "");
            line = KokoroRegex.QuoteMarker().Replace(line, "");
            line = KokoroRegex.Whitespace().Replace(line, " ").Trim();
            if (line.Length == 0) continue;
            if (result.Length > 0)
            {
                // Wrapped prose is joined without new pauses; structural boundaries retain a sentence break.
                int lastIndex = result.Length - 1;
                while (lastIndex > 0 && " )]\"'".Contains(result[lastIndex])) lastIndex--;
                char last = result[lastIndex];
                if ((paragraphBreak || listItem || heading || (previousList && !char.IsWhiteSpace(raw[0]))) && !".!?;:…".Contains(last)) result.Append('.');
                result.Append(' ');
            }
            result.Append(line);
            paragraphBreak = false;
            previousList = listItem || (previousList && char.IsWhiteSpace(raw[0]));
        }
        text = KokoroRegex.Whitespace().Replace(result.ToString(), " ").Trim();
        text = KokoroRegex.RepeatedPunctuation().Replace(text, "$1");
        return KokoroRegex.SpaceBeforePunctuation().Replace(text, "$1");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

using System.Globalization;
using System.Text;

namespace Lilith.Core.Kokoro;

/// <summary>Conservative speech cleanup; leaves pronunciation of numbers/abbreviations to the phonemizer.</summary>
public static class KokoroTtsSanitizer
{
    public static string Sanitize(string text)
    {
        ArgumentNullException.ThrowIfNull(text);
        // Remove fenced code before interpreting its contents as prose, including an unclosed fence.
        text = KokoroRegex.CodeFence().Replace(text, " ");
        text = KokoroRegex.MarkdownLink().Replace(text, "${label}");
        text = KokoroRegex.WebUrl().Replace(text, match =>
        {
            // Discard the address but retain punctuation ending the surrounding sentence.
            string url = match.Value.TrimEnd(')', ']', '}', '"', '\'');
            int end = url.Length;
            while (end > 0 && ".!?;:".Contains(url[end - 1])) end--;
            return " " + url[end..];
        });
        for (int pass = 0; pass < 3; pass++) text = KokoroRegex.Emphasis().Replace(text, "${value}");
        text = KokoroRegex.StrikeThrough().Replace(text, "${value}").Replace("`", "");
        text = KokoroIdentifiers.Expand(text);

        // Misaki can split surrogate pairs before normalization; spoken input excludes pictographs.
        // Grapheme rendering and the original chat/history text remain untouched.
        var spoken = new StringBuilder(text.Length);
        foreach (var rune in text.EnumerateRunes())
        {
            if (rune.Value is 0x200B or 0x2060 or 0xFEFF or 0x00AD) continue;
            bool unsupported = rune.Utf16SequenceLength == 2 || Rune.GetUnicodeCategory(rune) == UnicodeCategory.OtherSymbol ||
                rune.Value is 0x200D or 0xFE0E or 0xFE0F or 0xFFFD ||
                (Rune.GetUnicodeCategory(rune) == UnicodeCategory.Control && rune.Value is not (9 or 10 or 13));
            spoken.Append(unsupported ? " " : rune.ToString());
        }
        text = spoken.ToString().Normalize(NormalizationForm.FormC).Replace("\r\n", "\n").Replace('\r', '\n');
        var result = new StringBuilder(text.Length);
        bool paragraphBreak = false, previousList = false;
        foreach (string raw in text.Split('\n'))
        {
            string line = raw.Trim();
            if (line.Length == 0) { paragraphBreak = result.Length > 0; continue; }
            bool listItem = KokoroRegex.ListMarker().IsMatch(line);
            bool heading = KokoroRegex.HeadingMarker().IsMatch(line);
            line = KokoroRegex.ListMarker().Replace(line, "");
            line = KokoroRegex.HeadingMarker().Replace(line, "");
            line = KokoroRegex.QuoteMarker().Replace(line, "");
            line = KokoroRegex.Whitespace().Replace(line, " ").Trim();
            if (line.Length == 0) continue;
            if (result.Length > 0)
            {
                // Wrapped prose is joined without new pauses; structural boundaries retain a sentence break.
                int lastIndex = result.Length - 1;
                while (lastIndex > 0 && " )]\"'".Contains(result[lastIndex])) lastIndex--;
                char last = result[lastIndex];
                if ((paragraphBreak || listItem || heading || (previousList && !char.IsWhiteSpace(raw[0]))) && !".!?;:…".Contains(last)) result.Append('.');
                result.Append(' ');
            }
            result.Append(line);
            paragraphBreak = false;
            previousList = listItem || (previousList && char.IsWhiteSpace(raw[0]));
        }
        text = KokoroRegex.Whitespace().Replace(result.ToString(), " ").Trim();
        text = KokoroRegex.RepeatedPunctuation().Replace(text, "$1");
        return KokoroRegex.SpaceBeforePunctuation().Replace(text, "$1");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

namespace Lilith.Core.Logging;

/// <summary>Renders log types consistently; files retain the last update of each progress phase.</summary>
public sealed class TextLogSink(TextWriter writer, bool overwriteProgress = false, Func<int>? width = null)
{
    private readonly object _sync = new();
    private string? _progress;
    private int _drawnLength;
    private bool _inputActive;
    private readonly List<LogEntry> _deferred = [];

    /// <summary>Defer background output until the current console input has finished.</summary>
    public IDisposable BeginInput()
    {
        lock (_sync)
        {
            if (_inputActive) throw new InvalidOperationException("Console input is already active.");
            FinishProgress();
            _inputActive = true;
            return new TextLogInputLease(EndInput);
        }
    }

    public void Handle(LogEntry entry)
    {
        lock (_sync)
        {
            if (_inputActive && entry.Sender == "Scheduler" && entry.Type == LogType.WriteLine)
            {
                // Idle timer notices must be visible without requiring the user to submit input.
                writer.WriteLine();
                writer.WriteLine(entry.Description);
                writer.Write("You: ");
                writer.Flush();
                return;
            }
            if (_inputActive && !(entry.Sender == "Input" && entry.Type == LogType.Write))
            {
                if (entry.Type == LogType.Progress && _deferred.Count > 0 &&
                    _deferred[^1].Type == LogType.Progress && _deferred[^1].Sender == entry.Sender)
                    _deferred[^1] = entry;
                else _deferred.Add(entry);
                return;
            }
            if (entry.Type == LogType.Progress)
            {
                _progress = entry.Description;
                if (overwriteProgress)
                {
                    int available = Math.Max(1, width?.Invoke() ?? 120);
                    string text = entry.Description.Replace('\r', ' ').Replace('\n', ' ');
                    if (text.Length > available) text = text[..available];
                    writer.Write("\r" + text.PadRight(Math.Min(available, Math.Max(_drawnLength, text.Length))));
                    _drawnLength = text.Length;
                    writer.Flush();
                }
                return;
            }

            FinishProgress();
            if (entry.Type == LogType.Write) writer.Write(entry.Description);
            else writer.WriteLine(entry.Description);
            writer.Flush();
        }
    }

    public void Flush()
    {
        lock (_sync)
        {
            FinishProgress();
            writer.Flush();
        }
    }

    private void FinishProgress()
    {
        if (_progress is null) return;
        if (overwriteProgress) writer.WriteLine();
        else writer.WriteLine(_progress);
        _progress = null;
        _drawnLength = 0;
    }

    private void EndInput()
    {
        lock (_sync)
        {
            _inputActive = false;
            if (_deferred.Count > 0) writer.WriteLine();
            foreach (var entry in _deferred) Handle(entry);
            _deferred.Clear();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

namespace Lilith.Core.Logging;

/// <summary>Renders log types consistently; files retain the last update of each progress phase.</summary>
public sealed class TextLogSink(TextWriter writer, bool overwriteProgress = false, Func<int>? width = null)
{
    private readonly object _sync = new();
    private string? _progress;
    private int _drawnLength;
    private bool _inputActive;
    private readonly List<LogEntry> _deferred = [];

    /// <summary>Defer background output until the current console input has finished.</summary>
    public IDisposable BeginInput()
    {
        lock (_sync)
        {
            if (_inputActive) throw new InvalidOperationException("Console input is already active.");
            FinishProgress();
            _inputActive = true;
            return new TextLogInputLease(EndInput);
        }
    }

    public void Handle(LogEntry entry)
    {
        lock (_sync)
        {
            if (_inputActive && !(entry.Sender == "Input" && entry.Type == LogType.Write))
            {
                if (entry.Type == LogType.Progress && _deferred.Count > 0 &&
                    _deferred[^1].Type == LogType.Progress && _deferred[^1].Sender == entry.Sender)
                    _deferred[^1] = entry;
                else _deferred.Add(entry);
                return;
            }
            if (entry.Type == LogType.Progress)
            {
                _progress = entry.Description;
                if (overwriteProgress)
                {
                    int available = Math.Max(1, width?.Invoke() ?? 120);
                    string text = entry.Description.Replace('\r', ' ').Replace('\n', ' ');
                    if (text.Length > available) text = text[..available];
                    writer.Write("\r" + text.PadRight(Math.Min(available, Math.Max(_drawnLength, text.Length))));
                    _drawnLength = text.Length;
                    writer.Flush();
                }
                return;
            }

            FinishProgress();
            if (entry.Type == LogType.Write) writer.Write(entry.Description);
            else writer.WriteLine(entry.Description);
            writer.Flush();
        }
    }

    public void Flush()
    {
        lock (_sync)
        {
            FinishProgress();
            writer.Flush();
        }
    }

    private void FinishProgress()
    {
        if (_progress is null) return;
        if (overwriteProgress) writer.WriteLine();
        else writer.WriteLine(_progress);
        _progress = null;
        _drawnLength = 0;
    }

    private void EndInput()
    {
        lock (_sync)
        {
            _inputActive = false;
            if (_deferred.Count > 0) writer.WriteLine();
            foreach (var entry in _deferred) Handle(entry);
            _deferred.Clear();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333

namespace Lilith.Core.Providers;

using System.Text.Json;
using Lilith.Core.Tools;

/// <summary>Conversation operations reject overlap rather than mixing sessions or snapshots.</summary>
public abstract partial class ProviderClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : IDisposable
{
    private readonly bool _ownsHttp = httpClient is null;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private readonly Dictionary<string, ILilithTool> _tools = new(StringComparer.Ordinal);
    internal IReadOnlyDictionary<string, ILilithTool> RegisteredTools => _tools;
    public Lilith.Core.Workspace.WorkspaceSession? Workspace { get; private set; }
    public Lilith.Core.Scheduling.ScheduleSession? Schedules { get; private set; }
    internal bool ExecutingScheduledJob { get; private set; }
    public void ConfigureSchedules(Lilith.Core.Scheduling.ScheduleOptions options, string? scenarioRoot = null, TimeProvider? clock = null)
    {
        using var operation = EnterOperation();
        if (Schedules is not null) throw new InvalidOperationException("Schedules are fixed for this provider session.");
        Schedules = new(options, scenarioRoot, clock);
    }

    public void RecordScheduleEvent(Lilith.Core.Scheduling.ScheduleEvent item)
    {
        using var operation = EnterOperation();
        // Trusted application envelope; reminder text is data, never a new user instruction.
        History.Add("system", "Scheduler event (data): " + JsonSerializer.Serialize(new { item.Id, item.Name, item.Kind, item.AtUtc, item.Message }));
        SaveCore();
        Logger.WriteLine("Scheduler", item.Message, LogColors.Yellow);
    }

    public async Task<string> RunScheduledScenarioAsync(string name, IReadOnlyDictionary<string, string> inputs, CancellationToken ct = default)
    {
        using var operation = EnterOperation();
        ExecutingScheduledJob = true;
        try { return await RunScenarioCoreAsync(name, inputs, ct); }
        finally { ExecutingScheduledJob = false; }
    }
    public void ConfigureWorkspace(Lilith.Core.Workspace.WorkspaceOptions options)
    {
        using var operation = EnterOperation();
        if (Workspace is not null) throw new InvalidOperationException("Workspace mode and root are fixed for this provider session.");
        Workspace = new(options);
    }
    public async Task<string> ApproveWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        using var grant = (Workspace ?? throw new InvalidOperationException("No workspace configured.")).Authorize(id);
        return await RunScenarioCoreAsync("workspace_approve", new Dictionary<string, string> { ["bin_id"] = id }, cancellationToken);
    }
    public event Action<Lilith.Core.Scenarios.ScenarioProgress>? ScenarioProgress;
    internal void ReportScenario(Lilith.Core.Scenarios.ScenarioProgress progress)
    {
        ReportSubagent(progress);
        if (ScenarioProgress is not { } handlers) return;
        foreach (var handler in handlers.GetInvocationList().Cast<Action<Lilith.Core.Scenarios.ScenarioProgress>>())
            try { handler(progress); }
            catch (Exception ex) { Logger.WriteWarning("Scenario", "Progress observer failed: " + ex.Message); }
    }

    /// <summary>Fresh context with borrowed transport; never boots or reenters the parent.</summary>
    public virtual ProviderClient CreateScenarioBranch(string prompt, Logger branchLogger, ChatHistoryStore store) =>
        throw new NotSupportedException("This provider does not support scenario branches.");
    protected object[]? ToolDefinitions => _tools.Count == 0 ? null : _tools.Values.Select(t => (object)new
    {
        type = "function", function = new { name = t.Name, description = t.Description, parameters = t.Parameters }
    }).ToArray();

    public void RegisterTool(ILilithTool tool)
    {
        using var operation = EnterOperation();
        ArgumentNullException.ThrowIfNull(tool);
        if (string.IsNullOrWhiteSpace(tool.Name) || tool.Name.Length > 64 ||
            tool.Name.Any(c => !(char.IsAsciiLetterOrDigit(c) || c is '_' or '-')) ||
            tool.Parameters.ValueKind != JsonValueKind.Object)
            throw new ArgumentException("A tool requires a valid function name and JSON parameter schema.", nameof(tool));
        if (!_tools.TryAdd(tool.Name, tool)) throw new ArgumentException($"Tool '{tool.Name}' is already registered.", nameof(tool));
    }
    public HttpClient Http { get; } = httpClient ?? new() { Timeout = TimeSpan.FromMinutes(20) };
    public string Model { get; set; } = "gemma4";
    protected int NumCtx { get; set; } = 131072;
    public int ContextMax => NumCtx;
    public string SystemPrompt { get; protected set; } = string.Empty;
    /// <summary>Inspect only while idle. Use conversation methods to change an active session.</summary>
    public ChatHistory History { get; } = [];
    public ChatHistoryStore HistoryStore { get; } = historyStore ?? new ChatHistoryStore();
    public Logger Logger { get; } = logger;
    public string AgentName { get; set; } = "Lilith";
    public int ContextUsagePercent { get; private set; }
    public int CurrentContextTokens { get; private set; }
    public int ContextWarningThreshold { get; set; } = 60;
    public event Action<int>? OnContextHighUsage;

    public void ContextHighUsage(Func<int, string> message, string color = LogColors.Orange) =>
        OnContextHighUsage += pct => Logger.WriteLine("System", message(pct), color);

    protected void InitializeConversation()
    {
        History.Add("system", SystemPrompt);
        ContextHighUsage(pct => $"\u26a0 Context window is {pct}% full — history is getting long.");
    }

    private IDisposable EnterOperation()
    {
        var operation = _operation.EnterOrThrow("A conversation operation is already in progress.");
        if (_disposed) { operation.Dispose(); throw new ObjectDisposedException(GetType().Name); }
        return operation;
    }

    public void NewConversation()
    {
        using var operation = EnterOperation();
        SaveCore();
        HistoryStore.StartNewSession();
        ClearCore();
        Logger.WriteLine("System", "New conversation started.", LogColors.Cyan);
    }

    public void SaveConversation() => SaveCurrentConversation();
    public IReadOnlyList<ChatSessionSummary> ListConversations() => ListSavedConversations();
    public bool LoadConversation(int displayIndex) => LoadSavedConversation(displayIndex);
    public bool LoadConversation(string id) => LoadSavedConversation(id);
    public void ClearHistory() { using var operation = EnterOperation(); ClearCore(); }

    private void ClearCore()
    {
        History.Clear();
        ResetUsage();
        if (!string.IsNullOrWhiteSpace(SystemPrompt)) History.Add("system", SystemPrompt);
    }

    private void ResetUsage() { CurrentContextTokens = 0; ContextUsagePercent = 0; }
    public void StartNewSession() { using var operation = EnterOperation(); HistoryStore.StartNewSession(); }
    public void SaveCurrentConversation() { using var operation = EnterOperation(); SaveCore(); }

    private void SaveCore()
    {
        try
        {
            if (History.Any(m => !m.Role.Equals("system", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrWhiteSpace(m.Content)))
                HistoryStore.SaveSession(Model, History);
        }
        catch (Exception ex) { Logger.WriteWarning("History", $"Could not save chat history: {ex.Message}"); }
    }

    public IReadOnlyList<ChatSessionSummary> ListSavedConversations()
    {
        using var operation = EnterOperation();
        return HistoryStore.ListSessions();
    }

    public bool LoadSavedConversation(int displayIndex)
    {
        using var operation = EnterOperation();
        var sessions = HistoryStore.ListSessions();
        return displayIndex >= 1 && displayIndex <= sessions.Count && LoadCore(sessions[displayIndex - 1].Id);
    }

    public bool LoadSavedConversation(string id) { using var operation = EnterOperation(); return LoadCore(id); }

    private bool LoadCore(string id)
    {
        string previousId = HistoryStore.CurrentSessionId;
        try
        {
            var session = HistoryStore.LoadSession(id);
            if (session is null) return false;
            var messages = session.Messages.Select(m => m.ToChatMessage()).ToList();
            if (messages[0].Role != "system")
            {
                if (string.IsNullOrWhiteSpace(SystemPrompt)) throw new InvalidDataException("System prompt content is missing.");
                messages.Insert(0, new ChatMessage("system", SystemPrompt));
            }
            History.Clear();
            History.AddRange(messages);
            ResetUsage();
            return true;
        }
        catch (Exception ex)
        {
            HistoryStore.UseSession(previousId);
            Logger.WriteWarning("History", $"Could not load chat history: {ex.Message}");
            return false;
        }
    }

    protected abstract Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages);
    protected virtual Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages, CancellationToken cancellationToken) =>
        GenerateReplyAsync(messages);

    public async Task<string> StreamReply(string userInput, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        return await StreamReplyCoreAsync(userInput, images, cancellationToken);
    }

    /// <summary>Application-requested scenario dispatch; no model decision is needed to start it.</summary>
    public async Task<string> RunScenarioAsync(string scenarioName, IReadOnlyDictionary<string, string>? inputs = null,
        CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        return await RunScenarioCoreAsync(scenarioName, inputs, cancellationToken);
    }

    private async Task<string> RunScenarioCoreAsync(string scenarioName, IReadOnlyDictionary<string, string>? inputs,
        CancellationToken cancellationToken)
    {
        if (!_tools.TryGetValue("run_scenario", out var tool) || tool is not Lilith.Core.Scenarios.RunScenarioTool)
            throw new InvalidOperationException("Register scenario support before running a scenario.");
        var arguments = JsonSerializer.SerializeToElement(new { scenario_name = scenarioName, inputs = inputs ?? new Dictionary<string, string>() });
        var call = new ToolCall(new ToolFunction("run_scenario", arguments), "application-" + Guid.NewGuid().ToString("N"));
        var dispatch = new ChatChunk(new ChatMessage("assistant", "", ToolCalls: [call]), true, null, null);
        Logger.WriteLine("System", "Application requested scenario: " + scenarioName, LogColors.Cyan);
        return await StreamReplyCoreAsync(scenarioName == "greeting" ? "Please greet the user using the greeting scenario." : "Run " + scenarioName + " scenario.",
            null, cancellationToken, dispatch);
    }

    private async Task<string> StreamReplyCoreAsync(string userInput, List<string>? images, CancellationToken cancellationToken,
        ChatChunk? applicationDispatch = null)
    {
        bool requireScenarioSuccess = applicationDispatch is not null;
        if (string.IsNullOrWhiteSpace(userInput)) throw new ArgumentException("User input cannot be blank.", nameof(userInput));
        var userMessage = new ChatMessage("user", userInput, Images: images is null ? null : [.. images]);
        var requestHistory = History.Select(m => m.Snapshot()).ToList();
        requestHistory.Add(userMessage);
        Logger.WriteLine("User", $"User: {userInput}", LogColors.Green);
        ChatChunk? chunk;
        int originalCount = requestHistory.Count - 1;
        int rounds = 0;
        while (true)
        {
            cancellationToken.ThrowIfCancellationRequested();
            chunk = applicationDispatch ?? await GenerateReplyAsync(requestHistory, cancellationToken);
            applicationDispatch = null;
            cancellationToken.ThrowIfCancellationRequested();
            if (chunk is not { Done: true, Message.Role: "assistant" } ||
                chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
                throw new InvalidDataException("The model provider returned an invalid assistant response.");
            if (chunk.Message.ToolCalls is not { Count: > 0 } calls) break;
            if (++rounds > 8 || calls.Count > 16)
                throw new InvalidDataException("The model exceeded the tool execution limit.");
            foreach (var call in calls)
                if (call?.Function is null || string.IsNullOrWhiteSpace(call.Function.Name) ||
                    call.Function.Arguments.ValueKind != JsonValueKind.Object)
                    throw new InvalidDataException("The model returned a malformed tool call.");
            if (calls.Count != 1 && calls.Any(c => _tools.TryGetValue(c.Function.Name, out var candidate) && candidate is ITurnResultTool))
                throw new InvalidDataException("Run a scenario in its own tool batch so its final output is unambiguous.");
            requestHistory.Add(chunk.Message with { Content = chunk.Message.Content ?? string.Empty });
            string? exactReply = null;
            foreach (var call in calls)
            {
                cancellationToken.ThrowIfCancellationRequested();
                string result;
                if (!_tools.TryGetValue(call.Function.Name, out var tool))
                    result = JsonSerializer.Serialize(new { error = "Unknown tool: " + call.Function.Name });
                else
                {
                    using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
                    deadline.CancelAfter(tool is ITurnResultTool timed ? timed.ExecutionTimeout : TimeSpan.FromSeconds(30));
                    try
                    {
                        // Await actual completion: custom tools must cooperate with cancellation.
                        if (tool is ITurnResultTool turnTool)
                        {
                            var outcome = await turnTool.ExecuteResultAsync(call.Function.Arguments, deadline.Token);
                            deadline.Token.ThrowIfCancellationRequested();
                            if (requireScenarioSuccess && call.Function.Name == "run_scenario")
                            {
                                using var status = JsonDocument.Parse(outcome.Content);
                                string? scenarioStatus = status.RootElement.GetProperty("status").GetString();
                                if (scenarioStatus != "completed" && !(ExecutingScheduledJob && scenarioStatus == "needs_approval"))
                                    throw new InvalidDataException("Configured scenario did not complete: " + outcome.Content);
                            }
                            result = outcome.Content;
                            if (outcome.ExactReply is { } exact)
                            {
                                if (exactReply is not null) throw new InvalidDataException("Only one exact scenario output is allowed per tool batch.");
                                exactReply = exact;
                            }
                        }
                        else result = await tool.ExecuteAsync(call.Function.Arguments, deadline.Token);
                        deadline.Token.ThrowIfCancellationRequested();
                    }
                    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
                    catch (Exception ex) when (!requireScenarioSuccess && ex is not OutOfMemoryException)
                    {
                        result = JsonSerializer.Serialize(new { error = ex is OperationCanceledException ? "Tool execution canceled or timed out." : ex.Message });
                    }
                }
                requestHistory.Add(new ChatMessage("tool", result ?? string.Empty, ToolName: call.Function.Name, ToolCallId: call.Id));
            }
            if (exactReply is not null)
            {
                chunk = new ChatChunk(new ChatMessage("assistant", exactReply), true, null, null);
                break;
            }
        }
        cancellationToken.ThrowIfCancellationRequested();
        if (chunk is not { Done: true, Message: { Role: "assistant", Content: not null } } ||
            string.IsNullOrWhiteSpace(chunk.Message.Content) || chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
            throw new InvalidDataException("The model provider did not return a complete nonempty assistant reply with valid token counts.");
        string reply = chunk.Message.Content;
        // Commit only after a successful final answer.
        requestHistory[originalCount] = userMessage with { Tokens = chunk.PromptTokens };
        History.AddRange(requestHistory.Skip(originalCount).Select(m => m.Snapshot()));
        History.Add("assistant", reply, chunk.CompletionTokens);
        SaveCore();
        Logger.WriteLine(AgentName, $"{AgentName}: {reply}", LogColors.Yellow);
        ResetUsage();
        if (chunk.PromptTokens is { } prompt && chunk.CompletionTokens is { } completion && NumCtx > 0)
        {
            CurrentContextTokens = (int)Math.Min(int.MaxValue, (long)prompt + completion);
            ContextUsagePercent = (int)Math.Min(int.MaxValue, (long)CurrentContextTokens * 100 / NumCtx);
            if (ContextUsagePercent >= ContextWarningThreshold && OnContextHighUsage is { } handlers)
                foreach (var handler in handlers.GetInvocationList().Cast<Action<int>>())
                    try { handler(ContextUsagePercent); }
                    catch (Exception ex) { Logger.WriteWarning("System", $"Context warning callback failed: {ex.Message}"); }
        }
        return reply;
    }

    public void Dispose()
    {
        using var operation = _operation.EnterOrThrow("Cannot dispose a provider during a conversation operation.");
        if (_disposed) return;
        _disposed = true;
        Schedules?.Dispose();
        if (_ownsHttp) Http.Dispose();
        GC.SuppressFinalize(this);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306

namespace Lilith.Core.Providers;

using System.Text.Json;
using Lilith.Core.Tools;

/// <summary>Conversation operations reject overlap rather than mixing sessions or snapshots.</summary>
public abstract partial class ProviderClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : IDisposable
{
    private readonly bool _ownsHttp = httpClient is null;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private readonly Dictionary<string, ILilithTool> _tools = new(StringComparer.Ordinal);
    internal IReadOnlyDictionary<string, ILilithTool> RegisteredTools => _tools;
    public Lilith.Core.Workspace.WorkspaceSession? Workspace { get; private set; }
    public void ConfigureWorkspace(Lilith.Core.Workspace.WorkspaceOptions options)
    {
        using var operation = EnterOperation();
        if (Workspace is not null) throw new InvalidOperationException("Workspace mode and root are fixed for this provider session.");
        Workspace = new(options);
    }
    public async Task<string> ApproveWorkspaceAsync(string id, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        using var grant = (Workspace ?? throw new InvalidOperationException("No workspace configured.")).Authorize(id);
        return await RunScenarioCoreAsync("workspace_approve", new Dictionary<string, string> { ["bin_id"] = id }, cancellationToken);
    }
    public event Action<Lilith.Core.Scenarios.ScenarioProgress>? ScenarioProgress;
    internal void ReportScenario(Lilith.Core.Scenarios.ScenarioProgress progress)
    {
        ReportSubagent(progress);
        if (ScenarioProgress is not { } handlers) return;
        foreach (var handler in handlers.GetInvocationList().Cast<Action<Lilith.Core.Scenarios.ScenarioProgress>>())
            try { handler(progress); }
            catch (Exception ex) { Logger.WriteWarning("Scenario", "Progress observer failed: " + ex.Message); }
    }

    /// <summary>Fresh context with borrowed transport; never boots or reenters the parent.</summary>
    public virtual ProviderClient CreateScenarioBranch(string prompt, Logger branchLogger, ChatHistoryStore store) =>
        throw new NotSupportedException("This provider does not support scenario branches.");
    protected object[]? ToolDefinitions => _tools.Count == 0 ? null : _tools.Values.Select(t => (object)new
    {
        type = "function", function = new { name = t.Name, description = t.Description, parameters = t.Parameters }
    }).ToArray();

    public void RegisterTool(ILilithTool tool)
    {
        using var operation = EnterOperation();
        ArgumentNullException.ThrowIfNull(tool);
        if (string.IsNullOrWhiteSpace(tool.Name) || tool.Name.Length > 64 ||
            tool.Name.Any(c => !(char.IsAsciiLetterOrDigit(c) || c is '_' or '-')) ||
            tool.Parameters.ValueKind != JsonValueKind.Object)
            throw new ArgumentException("A tool requires a valid function name and JSON parameter schema.", nameof(tool));
        if (!_tools.TryAdd(tool.Name, tool)) throw new ArgumentException($"Tool '{tool.Name}' is already registered.", nameof(tool));
    }
    public HttpClient Http { get; } = httpClient ?? new() { Timeout = TimeSpan.FromMinutes(20) };
    public string Model { get; set; } = "gemma4";
    protected int NumCtx { get; set; } = 131072;
    public int ContextMax => NumCtx;
    public string SystemPrompt { get; protected set; } = string.Empty;
    /// <summary>Inspect only while idle. Use conversation methods to change an active session.</summary>
    public ChatHistory History { get; } = [];
    public ChatHistoryStore HistoryStore { get; } = historyStore ?? new ChatHistoryStore();
    public Logger Logger { get; } = logger;
    public string AgentName { get; set; } = "Lilith";
    public int ContextUsagePercent { get; private set; }
    public int CurrentContextTokens { get; private set; }
    public int ContextWarningThreshold { get; set; } = 60;
    public event Action<int>? OnContextHighUsage;

    public void ContextHighUsage(Func<int, string> message, string color = LogColors.Orange) =>
        OnContextHighUsage += pct => Logger.WriteLine("System", message(pct), color);

    protected void InitializeConversation()
    {
        History.Add("system", SystemPrompt);
        ContextHighUsage(pct => $"\u26a0 Context window is {pct}% full — history is getting long.");
    }

    private IDisposable EnterOperation()
    {
        var operation = _operation.EnterOrThrow("A conversation operation is already in progress.");
        if (_disposed) { operation.Dispose(); throw new ObjectDisposedException(GetType().Name); }
        return operation;
    }

    public void NewConversation()
    {
        using var operation = EnterOperation();
        SaveCore();
        HistoryStore.StartNewSession();
        ClearCore();
        Logger.WriteLine("System", "New conversation started.", LogColors.Cyan);
    }

    public void SaveConversation() => SaveCurrentConversation();
    public IReadOnlyList<ChatSessionSummary> ListConversations() => ListSavedConversations();
    public bool LoadConversation(int displayIndex) => LoadSavedConversation(displayIndex);
    public bool LoadConversation(string id) => LoadSavedConversation(id);
    public void ClearHistory() { using var operation = EnterOperation(); ClearCore(); }

    private void ClearCore()
    {
        History.Clear();
        ResetUsage();
        if (!string.IsNullOrWhiteSpace(SystemPrompt)) History.Add("system", SystemPrompt);
    }

    private void ResetUsage() { CurrentContextTokens = 0; ContextUsagePercent = 0; }
    public void StartNewSession() { using var operation = EnterOperation(); HistoryStore.StartNewSession(); }
    public void SaveCurrentConversation() { using var operation = EnterOperation(); SaveCore(); }

    private void SaveCore()
    {
        try
        {
            if (History.Any(m => !m.Role.Equals("system", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrWhiteSpace(m.Content)))
                HistoryStore.SaveSession(Model, History);
        }
        catch (Exception ex) { Logger.WriteWarning("History", $"Could not save chat history: {ex.Message}"); }
    }

    public IReadOnlyList<ChatSessionSummary> ListSavedConversations()
    {
        using var operation = EnterOperation();
        return HistoryStore.ListSessions();
    }

    public bool LoadSavedConversation(int displayIndex)
    {
        using var operation = EnterOperation();
        var sessions = HistoryStore.ListSessions();
        return displayIndex >= 1 && displayIndex <= sessions.Count && LoadCore(sessions[displayIndex - 1].Id);
    }

    public bool LoadSavedConversation(string id) { using var operation = EnterOperation(); return LoadCore(id); }

    private bool LoadCore(string id)
    {
        string previousId = HistoryStore.CurrentSessionId;
        try
        {
            var session = HistoryStore.LoadSession(id);
            if (session is null) return false;
            var messages = session.Messages.Select(m => m.ToChatMessage()).ToList();
            if (messages[0].Role != "system")
            {
                if (string.IsNullOrWhiteSpace(SystemPrompt)) throw new InvalidDataException("System prompt content is missing.");
                messages.Insert(0, new ChatMessage("system", SystemPrompt));
            }
            History.Clear();
            History.AddRange(messages);
            ResetUsage();
            return true;
        }
        catch (Exception ex)
        {
            HistoryStore.UseSession(previousId);
            Logger.WriteWarning("History", $"Could not load chat history: {ex.Message}");
            return false;
        }
    }

    protected abstract Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages);
    protected virtual Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages, CancellationToken cancellationToken) =>
        GenerateReplyAsync(messages);

    public async Task<string> StreamReply(string userInput, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        return await StreamReplyCoreAsync(userInput, images, cancellationToken);
    }

    /// <summary>Application-requested scenario dispatch; no model decision is needed to start it.</summary>
    public async Task<string> RunScenarioAsync(string scenarioName, IReadOnlyDictionary<string, string>? inputs = null,
        CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        return await RunScenarioCoreAsync(scenarioName, inputs, cancellationToken);
    }

    private async Task<string> RunScenarioCoreAsync(string scenarioName, IReadOnlyDictionary<string, string>? inputs,
        CancellationToken cancellationToken)
    {
        if (!_tools.TryGetValue("run_scenario", out var tool) || tool is not Lilith.Core.Scenarios.RunScenarioTool)
            throw new InvalidOperationException("Register scenario support before running a scenario.");
        var arguments = JsonSerializer.SerializeToElement(new { scenario_name = scenarioName, inputs = inputs ?? new Dictionary<string, string>() });
        var call = new ToolCall(new ToolFunction("run_scenario", arguments), "application-" + Guid.NewGuid().ToString("N"));
        var dispatch = new ChatChunk(new ChatMessage("assistant", "", ToolCalls: [call]), true, null, null);
        Logger.WriteLine("System", "Application requested scenario: " + scenarioName, LogColors.Cyan);
        return await StreamReplyCoreAsync(scenarioName == "greeting" ? "Please greet the user using the greeting scenario." : "Run " + scenarioName + " scenario.",
            null, cancellationToken, dispatch);
    }

    private async Task<string> StreamReplyCoreAsync(string userInput, List<string>? images, CancellationToken cancellationToken,
        ChatChunk? applicationDispatch = null)
    {
        bool requireScenarioSuccess = applicationDispatch is not null;
        if (string.IsNullOrWhiteSpace(userInput)) throw new ArgumentException("User input cannot be blank.", nameof(userInput));
        var userMessage = new ChatMessage("user", userInput, Images: images is null ? null : [.. images]);
        var requestHistory = History.Select(m => m.Snapshot()).ToList();
        requestHistory.Add(userMessage);
        Logger.WriteLine("User", $"User: {userInput}", LogColors.Green);
        ChatChunk? chunk;
        int originalCount = requestHistory.Count - 1;
        int rounds = 0;
        while (true)
        {
            cancellationToken.ThrowIfCancellationRequested();
            chunk = applicationDispatch ?? await GenerateReplyAsync(requestHistory, cancellationToken);
            applicationDispatch = null;
            cancellationToken.ThrowIfCancellationRequested();
            if (chunk is not { Done: true, Message.Role: "assistant" } ||
                chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
                throw new InvalidDataException("The model provider returned an invalid assistant response.");
            if (chunk.Message.ToolCalls is not { Count: > 0 } calls) break;
            if (++rounds > 8 || calls.Count > 16)
                throw new InvalidDataException("The model exceeded the tool execution limit.");
            foreach (var call in calls)
                if (call?.Function is null || string.IsNullOrWhiteSpace(call.Function.Name) ||
                    call.Function.Arguments.ValueKind != JsonValueKind.Object)
                    throw new InvalidDataException("The model returned a malformed tool call.");
            if (calls.Count != 1 && calls.Any(c => _tools.TryGetValue(c.Function.Name, out var candidate) && candidate is ITurnResultTool))
                throw new InvalidDataException("Run a scenario in its own tool batch so its final output is unambiguous.");
            requestHistory.Add(chunk.Message with { Content = chunk.Message.Content ?? string.Empty });
            string? exactReply = null;
            foreach (var call in calls)
            {
                cancellationToken.ThrowIfCancellationRequested();
                string result;
                if (!_tools.TryGetValue(call.Function.Name, out var tool))
                    result = JsonSerializer.Serialize(new { error = "Unknown tool: " + call.Function.Name });
                else
                {
                    using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
                    deadline.CancelAfter(tool is ITurnResultTool timed ? timed.ExecutionTimeout : TimeSpan.FromSeconds(30));
                    try
                    {
                        // Await actual completion: custom tools must cooperate with cancellation.
                        if (tool is ITurnResultTool turnTool)
                        {
                            var outcome = await turnTool.ExecuteResultAsync(call.Function.Arguments, deadline.Token);
                            deadline.Token.ThrowIfCancellationRequested();
                            if (requireScenarioSuccess && call.Function.Name == "run_scenario")
                            {
                                using var status = JsonDocument.Parse(outcome.Content);
                                if (status.RootElement.GetProperty("status").GetString() != "completed")
                                    throw new InvalidDataException("Configured scenario did not complete: " + outcome.Content);
                            }
                            result = outcome.Content;
                            if (outcome.ExactReply is { } exact)
                            {
                                if (exactReply is not null) throw new InvalidDataException("Only one exact scenario output is allowed per tool batch.");
                                exactReply = exact;
                            }
                        }
                        else result = await tool.ExecuteAsync(call.Function.Arguments, deadline.Token);
                        deadline.Token.ThrowIfCancellationRequested();
                    }
                    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
                    catch (Exception ex) when (!requireScenarioSuccess && ex is not OutOfMemoryException)
                    {
                        result = JsonSerializer.Serialize(new { error = ex is OperationCanceledException ? "Tool execution canceled or timed out." : ex.Message });
                    }
                }
                requestHistory.Add(new ChatMessage("tool", result ?? string.Empty, ToolName: call.Function.Name, ToolCallId: call.Id));
            }
            if (exactReply is not null)
            {
                chunk = new ChatChunk(new ChatMessage("assistant", exactReply), true, null, null);
                break;
            }
        }
        cancellationToken.ThrowIfCancellationRequested();
        if (chunk is not { Done: true, Message: { Role: "assistant", Content: not null } } ||
            string.IsNullOrWhiteSpace(chunk.Message.Content) || chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
            throw new InvalidDataException("The model provider did not return a complete nonempty assistant reply with valid token counts.");
        string reply = chunk.Message.Content;
        // Commit only after a successful final answer.
        requestHistory[originalCount] = userMessage with { Tokens = chunk.PromptTokens };
        History.AddRange(requestHistory.Skip(originalCount).Select(m => m.Snapshot()));
        History.Add("assistant", reply, chunk.CompletionTokens);
        SaveCore();
        Logger.WriteLine(AgentName, $"{AgentName}: {reply}", LogColors.Yellow);
        ResetUsage();
        if (chunk.PromptTokens is { } prompt && chunk.CompletionTokens is { } completion && NumCtx > 0)
        {
            CurrentContextTokens = (int)Math.Min(int.MaxValue, (long)prompt + completion);
            ContextUsagePercent = (int)Math.Min(int.MaxValue, (long)CurrentContextTokens * 100 / NumCtx);
            if (ContextUsagePercent >= ContextWarningThreshold && OnContextHighUsage is { } handlers)
                foreach (var handler in handlers.GetInvocationList().Cast<Action<int>>())
                    try { handler(ContextUsagePercent); }
                    catch (Exception ex) { Logger.WriteWarning("System", $"Context warning callback failed: {ex.Message}"); }
        }
        return reply;
    }

    public void Dispose()
    {
        using var operation = _operation.EnterOrThrow("Cannot dispose a provider during a conversation operation.");
        if (_disposed) return;
        _disposed = true;
        if (_ownsHttp) Http.Dispose();
        GC.SuppressFinalize(this);
    }

}