Only the delta.

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

<Project>
  <!-- V3 development. V2 is preserved by v2.0.0 and release/v2. -->
  <PropertyGroup>
    <VersionPrefix>3.0.0</VersionPrefix>
    <VersionSuffix>alpha.2</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

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

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);
                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
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
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

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 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

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

namespace Lilith.Agent;

public partial class Lilith
{
    partial void RegisterWorkspaceCommands(ChatCommandRegistry commands)
    {
        commands.RegisterAsync("workspace", "List proposals; /workspace review <id> inspects one. Access mode is fixed at boot.", async context =>
        {
            string output = context.Arguments switch
            {
                "" => JsonSerializer.Serialize(await Workspace.ExecuteAsync(new("pending"), context.CancellationToken)),
                var args when args.StartsWith("review ", StringComparison.OrdinalIgnoreCase) => JsonSerializer.Serialize(Workspace.Review(args[7..].Trim()), new JsonSerializerOptions { WriteIndented = true }),
                _ => "Workspace mode is fixed at boot. Restart to choose ask or yolo."
            };
            return new(true, output);
        });
        commands.RegisterAsync("approve", "Approve an exact workspace proposal: /approve <id>.", async context => { await ApproveWorkspaceAsync(context.Arguments, context.CancellationToken); return new(true); });
        commands.RegisterAsync("reject", "Reject a workspace proposal: /reject <id>.", async context => { await RejectWorkspaceAsync(context.Arguments, context.CancellationToken); return new(true); });
    }
}

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
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

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 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)
    {
        _llmclient = ProviderFactory is { } factory ? await factory(startServerIfNotRunning) : await this.CreateClient(startServerIfNotRunning);
        _llmclient.ShowSubagentOutput = _showSubagentOutput;
        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

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
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

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
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);
    }

}

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

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 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();
        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);
    }

}

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

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

namespace Lilith.Core.Scenarios;

/// <summary>Loads trusted saved XML, fills values as data, and passes the complete document to the executor.</summary>
public sealed class RunScenarioTool(ProviderClient parent, ScenarioFileService files) : ITurnResultTool
{
    public string Name => "run_scenario";
    public string Description => "Run a named saved scenario in a fresh sub-agent conversation. " +
        "Use this when the user says run X scenario. Supply input values in inputs. " +
        "If status is needs_input, ask the user for the missing values before retrying. " +
        "Do not retry a failed scenario without a new user request. " +
        "For exit mode respond, follow exit_request when composing the final answer. " +
        "For workspace data management, always delegate to a workspace scenario. Search with workspace_search and read only selected excerpts. " +
        "Never approve a workspace proposal yourself or change access mode. " +
        "Available scenarios and input names: " + string.Join("; ", files.ListNames().Select(name =>
        { var scenario = ScenarioXmlParser.Parse(files.LoadScenarioXml(name)); return name + "(" + string.Join(", ", scenario.Inputs.Select(i => i.Name + (i.Required ? " required" : ""))) + ")"; }));
    public JsonElement Parameters => JsonSerializer.SerializeToElement(new
    {
        type = "object", properties = new
        {
            scenario_name = new { type = "string", description = "Saved scenario name, without .xml." },
            inputs = new { type = "object", additionalProperties = new { type = "string" }, description = "Named scenario input values." }
        }, required = new[] { "scenario_name" }, additionalProperties = false
    });
    public TimeSpan ExecutionTimeout => TimeSpan.FromMinutes(10);
    public async Task<string> ExecuteAsync(JsonElement arguments, CancellationToken cancellationToken = default) =>
        (await ExecuteResultAsync(arguments, cancellationToken)).Content;

    public async Task<ToolExecutionResult> ExecuteResultAsync(JsonElement arguments, CancellationToken cancellationToken)
    {
        if (arguments.ValueKind != JsonValueKind.Object || !arguments.TryGetProperty("scenario_name", out var name) || name.ValueKind != JsonValueKind.String ||
            arguments.EnumerateObject().Any(p => p.Name is not ("scenario_name" or "inputs")))
            throw new ArgumentException("Expected scenario_name and optional inputs.");
        string xml = files.LoadScenarioXml(name.GetString()!);
        var definition = ScenarioXmlParser.Parse(xml);
        var supplied = new Dictionary<string, string>(StringComparer.Ordinal);
        if (arguments.TryGetProperty("inputs", out var inputValues))
        {
            if (inputValues.ValueKind != JsonValueKind.Object) throw new ArgumentException("inputs must be an object of string values.");
            foreach (var property in inputValues.EnumerateObject())
            {
                if (property.Value.ValueKind != JsonValueKind.String || !definition.Inputs.Any(i => i.Name == property.Name) ||
                    !supplied.TryAdd(property.Name, property.Value.GetString()!) || supplied[property.Name].Length > 20000)
                    throw new ArgumentException("Unknown, duplicate, or invalid scenario input: " + property.Name);
            }
        }
        var document = ScenarioXmlParser.Read(xml);
        foreach (var input in document.Root!.Element("inputs")?.Elements("input") ?? [])
            if (supplied.TryGetValue((string)input.Attribute("name")!, out var value)) input.SetAttributeValue("value", value);
        string fullXml = document.ToString(SaveOptions.DisableFormatting);
        var filled = ScenarioXmlParser.Parse(fullXml);
        string[] missing = filled.Inputs.Where(i => i.Required && string.IsNullOrWhiteSpace(i.Value)).Select(i => i.Name).ToArray();
        if (missing.Length > 0)
            return new ToolExecutionResult(JsonSerializer.Serialize(new { status = "needs_input", scenario = definition.Id, missing,
                request = "Ask the user for these values. No scenario steps have run." }),
                "Please provide the following values for the " + definition.Title + " scenario: " + string.Join(", ", missing) + ".");
        ScenarioRunResult run;
        try { run = await new ScenarioExecutor(parent).RunXmlAsync(fullXml, cancellationToken); }
        catch (ScenarioExecutionException ex)
        {
            return new ToolExecutionResult(JsonSerializer.Serialize(new { status = "failed", run_id = ex.RunId, error = ex.Message }));
        }
        if (run.Workspace is { } storage)
            return new ToolExecutionResult(JsonSerializer.Serialize(new { status = storage.Status, run_id = run.RunId, result = storage,
                exit_mode = run.ExitMode, exit_request = run.ExitRequest }),
                storage.Status == "needs_approval" || run.ExitMode == "copy" ? storage.ToReply() : null);
        return new ToolExecutionResult(JsonSerializer.Serialize(new
        {
            status = "completed", run_id = run.RunId, scenario = run.ScenarioId, output = run.Output,
            exit_mode = run.ExitMode, exit_request = run.ExitRequest
        }), run.ExitMode == "copy" ? run.Output : null);
    }
}

public static class ScenarioTools
{
    public static void Register(ProviderClient provider, string? scenarioRoot = null) =>
        provider.RegisterTool(new RunScenarioTool(provider, new ScenarioFileService(scenarioRoot)));
}

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

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

namespace Lilith.Core.Scenarios;

/// <summary>Loads trusted saved XML, fills values as data, and passes the complete document to the executor.</summary>
public sealed class RunScenarioTool(ProviderClient parent, ScenarioFileService files) : ITurnResultTool
{
    public string Name => "run_scenario";
    public string Description => "Run a named saved scenario in a fresh sub-agent conversation. " +
        "Use this when the user says run X scenario. Supply input values in inputs. " +
        "If status is needs_input, ask the user for the missing values before retrying. " +
        "Do not retry a failed scenario without a new user request. " +
        "For exit mode respond, follow exit_request when composing the final answer. " +
        "Available scenarios: " + string.Join(", ", files.ListNames());
    public JsonElement Parameters => JsonSerializer.SerializeToElement(new
    {
        type = "object", properties = new
        {
            scenario_name = new { type = "string", description = "Saved scenario name, without .xml." },
            inputs = new { type = "object", additionalProperties = new { type = "string" }, description = "Named scenario input values." }
        }, required = new[] { "scenario_name" }, additionalProperties = false
    });
    public TimeSpan ExecutionTimeout => TimeSpan.FromMinutes(10);
    public async Task<string> ExecuteAsync(JsonElement arguments, CancellationToken cancellationToken = default) =>
        (await ExecuteResultAsync(arguments, cancellationToken)).Content;

    public async Task<ToolExecutionResult> ExecuteResultAsync(JsonElement arguments, CancellationToken cancellationToken)
    {
        if (arguments.ValueKind != JsonValueKind.Object || !arguments.TryGetProperty("scenario_name", out var name) || name.ValueKind != JsonValueKind.String ||
            arguments.EnumerateObject().Any(p => p.Name is not ("scenario_name" or "inputs")))
            throw new ArgumentException("Expected scenario_name and optional inputs.");
        string xml = files.LoadScenarioXml(name.GetString()!);
        var definition = ScenarioXmlParser.Parse(xml);
        var supplied = new Dictionary<string, string>(StringComparer.Ordinal);
        if (arguments.TryGetProperty("inputs", out var inputValues))
        {
            if (inputValues.ValueKind != JsonValueKind.Object) throw new ArgumentException("inputs must be an object of string values.");
            foreach (var property in inputValues.EnumerateObject())
            {
                if (property.Value.ValueKind != JsonValueKind.String || !definition.Inputs.Any(i => i.Name == property.Name) ||
                    !supplied.TryAdd(property.Name, property.Value.GetString()!) || supplied[property.Name].Length > 20000)
                    throw new ArgumentException("Unknown, duplicate, or invalid scenario input: " + property.Name);
            }
        }
        var document = ScenarioXmlParser.Read(xml);
        foreach (var input in document.Root!.Element("inputs")?.Elements("input") ?? [])
            if (supplied.TryGetValue((string)input.Attribute("name")!, out var value)) input.SetAttributeValue("value", value);
        string fullXml = document.ToString(SaveOptions.DisableFormatting);
        var filled = ScenarioXmlParser.Parse(fullXml);
        string[] missing = filled.Inputs.Where(i => i.Required && string.IsNullOrWhiteSpace(i.Value)).Select(i => i.Name).ToArray();
        if (missing.Length > 0)
            return new ToolExecutionResult(JsonSerializer.Serialize(new { status = "needs_input", scenario = definition.Id, missing,
                request = "Ask the user for these values. No scenario steps have run." }),
                "Please provide the following values for the " + definition.Title + " scenario: " + string.Join(", ", missing) + ".");
        ScenarioRunResult run;
        try { run = await new ScenarioExecutor(parent).RunXmlAsync(fullXml, cancellationToken); }
        catch (ScenarioExecutionException ex)
        {
            return new ToolExecutionResult(JsonSerializer.Serialize(new { status = "failed", run_id = ex.RunId, error = ex.Message }));
        }
        return new ToolExecutionResult(JsonSerializer.Serialize(new
        {
            status = "completed", run_id = run.RunId, scenario = run.ScenarioId, output = run.Output,
            exit_mode = run.ExitMode, exit_request = run.ExitRequest
        }), run.ExitMode == "copy" ? run.Output : null);
    }
}

public static class ScenarioTools
{
    public static void Register(ProviderClient provider, string? scenarioRoot = null) =>
        provider.RegisterTool(new RunScenarioTool(provider, new ScenarioFileService(scenarioRoot)));
}

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.Text.Json;
using Lilith.Core.Tools;

namespace Lilith.Core.Scenarios;

public sealed record ScenarioRunResult(string RunId, string ScenarioId, string Output, string ExitMode, string ExitRequest, Lilith.Core.Workspace.WorkspaceResult? Workspace = null);
public sealed class ScenarioExecutionException(string runId, Exception inner)
    : Exception(inner.Message, inner)
{
    public string RunId { get; } = runId;
}

public sealed class ScenarioExecutor(ProviderClient parent)
{
    /// <summary>Application API for trusted full XML. Model calls should use the saved-file scenario tool.</summary>
    public async Task<ScenarioRunResult> RunXmlAsync(string completeXml, CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        var scenario = ScenarioXmlParser.Parse(completeXml);
        string[] missing = scenario.Inputs.Where(i => i.Required && string.IsNullOrWhiteSpace(i.Value)).Select(i => i.Name).ToArray();
        if (missing.Length > 0) throw new ArgumentException("Missing required scenario inputs: " + string.Join(", ", missing));
        var values = scenario.Inputs.ToDictionary(i => i.Name, i => i.Value ?? string.Empty, StringComparer.Ordinal);
        // Validate every substitution/tool reference before compiling code or running a chat turn.
        string prompt = ScenarioXmlParser.Expand(scenario.SystemPrompt, values);
        string[] steps = scenario.Steps.Select(s => ScenarioXmlParser.Expand(s, values)).ToArray();
        string exit = ScenarioXmlParser.Expand(scenario.ExitRequest, values);
        var workspaceNames = scenario.AllowedTools.Where(n => Lilith.Core.Workspace.WorkspaceTool.Operation(n) is not null).ToArray();
        if (workspaceNames.Length > 0 && (parent.Workspace is null || scenario.Steps.Length != 1 || scenario.AllowedTools.Length != 1 || scenario.CodeTools.Length != 0))
            throw new InvalidDataException("Workspace scenarios require a configured workspace, one step, one workspace operation, and no embedded code.");
        foreach (string tool in scenario.AllowedTools)
            if (!workspaceNames.Contains(tool) && (!parent.RegisteredTools.ContainsKey(tool) || parent.RegisteredTools[tool] is ITurnResultTool))
                throw new InvalidDataException("Unavailable or nested scenario tool: " + tool);
        string runId = Guid.NewGuid().ToString("N");
        string folder = Path.Combine(parent.HistoryStore.RootDirectory, "Scenarios", runId);
        Directory.CreateDirectory(folder);
        using var transcript = new StreamWriter(Path.Combine(folder, "session.log")) { AutoFlush = true };
        await File.WriteAllTextAsync(Path.Combine(folder, "scenario.xml"), completeXml, cancellationToken);
        void Report(string kind, string text, int step)
        {
            transcript.WriteLine($"{DateTimeOffset.UtcNow:O} [{kind}] {text}");
            parent.ReportScenario(new ScenarioProgress(runId, scenario.Id, kind, text, step, steps.Length));
        }
        Report("Started", scenario.Title, 0);
        using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        deadline.CancelAfter(TimeSpan.FromMinutes(10));
        var ct = deadline.Token;
        try
        {
            using var compiler = await ScenarioCodeCompiler.CompileAsync(scenario.CodeTools, values, ct);
            using var child = parent.CreateScenarioBranch(prompt, new Logger(), new ChatHistoryStore(Path.Combine(folder, "History")));
            child.AgentName = "Scenario:" + scenario.Id;
            Lilith.Core.Workspace.WorkspaceResult? storageResult = null;
            foreach (string name in scenario.AllowedTools)
            {
                if (workspaceNames.Contains(name)) child.RegisterTool(new Lilith.Core.Workspace.WorkspaceTool(parent.Workspace!, Lilith.Core.Workspace.WorkspaceTool.Operation(name)!, values, result => storageResult = result));
                else child.RegisterTool(parent.RegisteredTools[name]);
            }
            foreach (var tool in compiler.Tools) child.RegisterTool(tool);
            string? last = null;
            for (int i = 0; i < steps.Length; i++)
            {
                ct.ThrowIfCancellationRequested();
                Report("Step", $"{i + 1}/{steps.Length}: {steps[i]}", i + 1);
                int historyCount = child.History.Count;
                last = await child.StreamReply(steps[i], cancellationToken: ct);
                foreach (var toolResult in child.History.Skip(historyCount).Where(m => m.Role == "tool"))
                    Report("Tool", toolResult.ToolName + ": " + toolResult.Content, i + 1);
                Report("Reply", last, i + 1);
            }
            ct.ThrowIfCancellationRequested();
            if (string.IsNullOrWhiteSpace(last)) throw new InvalidDataException("Scenario produced no final response.");
            if (workspaceNames.Length > 0 && storageResult is null) throw new InvalidDataException("The scenario did not perform its workspace operation. No completion is claimed.");
            var result = new ScenarioRunResult(runId, scenario.Id, last, scenario.ExitMode, exit, storageResult);
            await File.WriteAllTextAsync(Path.Combine(folder, "result.json"), JsonSerializer.Serialize(result, new JsonSerializerOptions { WriteIndented = true }), ct);
            Report(storageResult?.Status == "needs_approval" ? "NeedsApproval" : "Completed", "Result returned to caller.", steps.Length);
            return result;
        }
        catch (Exception ex)
        {
            await File.WriteAllTextAsync(Path.Combine(folder, "failure.json"), JsonSerializer.Serialize(new
            {
                RunId = runId, ScenarioId = scenario.Id, Status = ex is OperationCanceledException ? "canceled" : "failed", Error = ex.Message
            }));
            Report(ex is OperationCanceledException ? "Canceled" : "Failed", ex.Message, 0);
            if (ex is OperationCanceledException) throw;
            throw new ScenarioExecutionException(runId, ex);
        }
    }
}

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