feat(agentic): Phase 4 — trajectory capture (self-improvement foundation) (#1544)

The raw material every self-improvement mechanism learns from:

- AgentTrajectory: a captured run (transcript, final answer, iterations, usage, agent name, optional evaluator-assigned Reward, metadata).

- ITrajectoryStore (Add/Get/GetAll/Query/Clear) + InMemoryTrajectoryStore.

- TracingAgent<T> (IAgent<T>): transparently records each run of any wrapped agent (executor/supervisor/swarm/memory) to the store without changing behavior; supports per-experiment metadata.

- 5 tests (green net10.0 + net471): records runs, accumulates + queryable, metadata, get-by-id + reward annotation, clear. net471 nullability fix on GetAsync (Task.FromResult<AgentTrajectory?>). No null-forgiving.

Stacked on Phase 3 (#1552). Next: eval harness scoring trajectories with the existing reward models, then learned routing / prompt-opt / online LoRA. Part of epic #1544 (Phase 4).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: franklinic

src/Agentic/SelfImproving/AgentTrajectory.cs

@@ -0,0 +1,89 @@
+using AiDotNet.Agentic.Models;
+
+// Disambiguate from the legacy AiDotNet.PromptEngineering.Templates.ChatMessage (global using).
+using ChatMessage = AiDotNet.Agentic.Models.ChatMessage;
+
+namespace AiDotNet.Agentic.SelfImproving;
+
+/// <summary>
+/// A captured record of one agent run — the structured "trajectory" the self-improving layer learns from.
+/// It pairs what the agent did (the full message transcript, the final answer, step count, token usage) with
+/// an optional quality <see cref="Reward"/> assigned later by an evaluator.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Trajectories are the raw material for every self-improvement mechanism: continuous evaluation scores them,
+/// learned routers/tool policies train on them, prompt optimizers measure prompts against them, and
+/// reward-filtered trajectories become fine-tuning (LoRA) data. Capturing a run is non-invasive — a
+/// <see cref="TracingAgent{T}"/> wraps any agent and records each run without changing its behavior.
+/// </para>
+/// <para><b>For Beginners:</b> Think of this as the flight recorder for an agent: it saves exactly what was
+/// said and done on a run, plus (once graded) how good the outcome was. Collect many of these and the system
+/// can learn what works and get better over time.
+/// </para>
+/// </remarks>
+public sealed class AgentTrajectory
+{
+    /// <summary>
+    /// Initializes a new trajectory.
+    /// </summary>
+    /// <param name="id">The unique id for this trajectory.</param>
+    /// <param name="agentName">The name of the agent that produced the run.</param>
+    /// <param name="messages">The full conversation transcript the run produced.</param>
+    /// <param name="finalText">The agent's final answer.</param>
+    /// <param name="iterations">The number of model calls the run took.</param>
+    /// <param name="usage">Aggregate token usage, when available.</param>
+    /// <param name="reward">An optional quality score (assigned by an evaluator). <c>null</c> until graded.</param>
+    /// <param name="metadata">Optional key/value metadata.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/>, <paramref name="agentName"/>, <paramref name="messages"/>, or <paramref name="finalText"/> is <c>null</c>.</exception>
+    public AgentTrajectory(
+        string id,
+        string agentName,
+        IReadOnlyList<ChatMessage> messages,
+        string finalText,
+        int iterations,
+        ChatUsage? usage = null,
+        double? reward = null,
+        IReadOnlyDictionary<string, string>? metadata = null)
+    {
+        Guard.NotNullOrWhiteSpace(id);
+        Guard.NotNull(agentName);
+        Guard.NotNull(messages);
+        Guard.NotNull(finalText);
+        Id = id;
+        AgentName = agentName;
+        Messages = messages;
+        FinalText = finalText;
+        Iterations = iterations;
+        Usage = usage;
+        Reward = reward;
+        Metadata = metadata;
+    }
+
+    /// <summary>Gets the unique id for this trajectory.</summary>
+    public string Id { get; }
+
+    /// <summary>Gets the name of the agent that produced the run.</summary>
+    public string AgentName { get; }
+
+    /// <summary>Gets the full conversation transcript the run produced.</summary>
+    public IReadOnlyList<ChatMessage> Messages { get; }
+
+    /// <summary>Gets the agent's final answer.</summary>
+    public string FinalText { get; }
+
+    /// <summary>Gets the number of model calls the run took.</summary>
+    public int Iterations { get; }
+
+    /// <summary>Gets aggregate token usage, or <c>null</c> when not reported.</summary>
+    public ChatUsage? Usage { get; }
+
+    /// <summary>
+    /// Gets or sets the quality score for this trajectory, assigned by an evaluator (higher is better), or
+    /// <c>null</c> while ungraded.
+    /// </summary>
+    public double? Reward { get; set; }
+
+    /// <summary>Gets optional key/value metadata, or <c>null</c> when none was supplied.</summary>
+    public IReadOnlyDictionary<string, string>? Metadata { get; }
+}

src/Agentic/SelfImproving/ITrajectoryStore.cs

@@ -0,0 +1,49 @@
+namespace AiDotNet.Agentic.SelfImproving;
+
+/// <summary>
+/// Stores captured <see cref="AgentTrajectory"/> records so the self-improving layer can replay, evaluate,
+/// and learn from past agent runs.
+/// </summary>
+/// <remarks>
+/// <para><b>For Beginners:</b> This is the logbook of everything the agents have done. Other parts of the
+/// system read from it to grade past runs and figure out how to do better next time.
+/// </para>
+/// </remarks>
+public interface ITrajectoryStore
+{
+    /// <summary>
+    /// Adds a trajectory and returns its id.
+    /// </summary>
+    /// <param name="trajectory">The trajectory to store.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    /// <returns>The stored trajectory's id.</returns>
+    Task<string> AddAsync(AgentTrajectory trajectory, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a trajectory by id, or <c>null</c> when not found.
+    /// </summary>
+    /// <param name="id">The trajectory id.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task<AgentTrajectory?> GetAsync(string id, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns all stored trajectories, oldest first.
+    /// </summary>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task<IReadOnlyList<AgentTrajectory>> GetAllAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns the trajectories matching a predicate, oldest first.
+    /// </summary>
+    /// <param name="predicate">The filter to apply.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task<IReadOnlyList<AgentTrajectory>> QueryAsync(
+        Func<AgentTrajectory, bool> predicate,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes all stored trajectories.
+    /// </summary>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task ClearAsync(CancellationToken cancellationToken = default);
+}

src/Agentic/SelfImproving/InMemoryTrajectoryStore.cs

@@ -0,0 +1,73 @@
+namespace AiDotNet.Agentic.SelfImproving;
+
+/// <summary>
+/// A process-local <see cref="ITrajectoryStore"/> that keeps captured runs in memory. Ideal for tests and
+/// single-process self-improvement loops; contents are lost when the process exits.
+/// </summary>
+/// <remarks>
+/// <para><b>For Beginners:</b> The simplest logbook, kept in RAM — fast and zero-config, but not saved to
+/// disk. Swap in a durable store when you need trajectories to persist across restarts.
+/// </para>
+/// </remarks>
+public sealed class InMemoryTrajectoryStore : ITrajectoryStore
+{
+    private readonly object _gate = new();
+    private readonly List<AgentTrajectory> _trajectories = new();
+
+    /// <inheritdoc/>
+    public Task<string> AddAsync(AgentTrajectory trajectory, CancellationToken cancellationToken = default)
+    {
+        Guard.NotNull(trajectory);
+        lock (_gate)
+        {
+            _trajectories.Add(trajectory);
+        }
+
+        return Task.FromResult(trajectory.Id);
+    }
+
+    /// <inheritdoc/>
+    public Task<AgentTrajectory?> GetAsync(string id, CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(id);
+        lock (_gate)
+        {
+            AgentTrajectory? match = _trajectories.FirstOrDefault(t => string.Equals(t.Id, id, StringComparison.Ordinal));
+            return Task.FromResult<AgentTrajectory?>(match);
+        }
+    }
+
+    /// <inheritdoc/>
+    public Task<IReadOnlyList<AgentTrajectory>> GetAllAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_gate)
+        {
+            IReadOnlyList<AgentTrajectory> all = new List<AgentTrajectory>(_trajectories);
+            return Task.FromResult(all);
+        }
+    }
+
+    /// <inheritdoc/>
+    public Task<IReadOnlyList<AgentTrajectory>> QueryAsync(
+        Func<AgentTrajectory, bool> predicate,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNull(predicate);
+        lock (_gate)
+        {
+            IReadOnlyList<AgentTrajectory> matches = _trajectories.Where(predicate).ToList();
+            return Task.FromResult(matches);
+        }
+    }
+
+    /// <inheritdoc/>
+    public Task ClearAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_gate)
+        {
+            _trajectories.Clear();
+        }
+
+        return Task.CompletedTask;
+    }
+}

src/Agentic/SelfImproving/TracingAgent.cs

@@ -0,0 +1,74 @@
+using AiDotNet.Agentic.Agents;
+using AiDotNet.Agentic.Models;
+
+// Disambiguate from the legacy AiDotNet.PromptEngineering.Templates.ChatMessage (global using).
+using ChatMessage = AiDotNet.Agentic.Models.ChatMessage;
+
+namespace AiDotNet.Agentic.SelfImproving;
+
+/// <summary>
+/// Wraps any <see cref="IAgent{T}"/> and records each run as an <see cref="AgentTrajectory"/> in a
+/// <see cref="ITrajectoryStore"/>, without altering the agent's behavior. This is how the self-improving
+/// layer collects the experience it later evaluates and learns from.
+/// </summary>
+/// <typeparam name="T">The numeric type shared across the agent stack.</typeparam>
+/// <remarks>
+/// <para>
+/// Tracing is transparent and composable: the wrapper returns exactly what the inner agent returns and can
+/// itself wrap (or be wrapped by) memory, supervisor, or swarm agents. Capture failures never affect the
+/// run — the result is returned regardless of whether the store accepts the trajectory.
+/// </para>
+/// <para><b>For Beginners:</b> Put this around an agent and every time it runs, a copy of what happened is
+/// filed away for later study. The agent itself behaves no differently; you just end up with a logbook.
+/// </para>
+/// </remarks>
+public sealed class TracingAgent<T> : IAgent<T>
+{
+    private readonly IAgent<T> _inner;
+    private readonly ITrajectoryStore _store;
+    private readonly IReadOnlyDictionary<string, string>? _metadata;
+
+    /// <summary>
+    /// Initializes a new tracing wrapper.
+    /// </summary>
+    /// <param name="inner">The agent whose runs are recorded.</param>
+    /// <param name="store">The store that receives each trajectory.</param>
+    /// <param name="metadata">Optional metadata attached to every captured trajectory (e.g., experiment id).</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="inner"/> or <paramref name="store"/> is <c>null</c>.</exception>
+    public TracingAgent(IAgent<T> inner, ITrajectoryStore store, IReadOnlyDictionary<string, string>? metadata = null)
+    {
+        Guard.NotNull(inner);
+        Guard.NotNull(store);
+        _inner = inner;
+        _store = store;
+        _metadata = metadata;
+    }
+
+    /// <inheritdoc/>
+    public string Name => _inner.Name;
+
+    /// <inheritdoc/>
+    public string Description => _inner.Description;
+
+    /// <inheritdoc/>
+    public async Task<AgentRunResult> RunAsync(
+        IReadOnlyList<ChatMessage> messages,
+        CancellationToken cancellationToken = default)
+    {
+        var result = await _inner.RunAsync(messages, cancellationToken).ConfigureAwait(false);
+
+        var trajectory = new AgentTrajectory(
+            Guid.NewGuid().ToString("N"),
+            result.AgentName is { } name && name.Trim().Length > 0 ? name : _inner.Name,
+            result.Messages,
+            result.FinalText,
+            result.Iterations,
+            result.Usage,
+            reward: null,
+            _metadata);
+
+        await _store.AddAsync(trajectory, cancellationToken).ConfigureAwait(false);
+
+        return result;
+    }
+}

tests/AiDotNet.Tests/UnitTests/Agentic/SelfImproving/TrajectoryCaptureTests.cs

@@ -0,0 +1,93 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using AiDotNet.Agentic.Agents;
+using AiDotNet.Agentic.Models;
+using AiDotNet.Agentic.SelfImproving;
+using AiDotNetTests.UnitTests.Agentic.Agents;
+using Xunit;
+
+namespace AiDotNetTests.UnitTests.Agentic.SelfImproving
+{
+    public class TrajectoryCaptureTests
+    {
+        private static AgentExecutor<double> Agent(string name, string answer)
+        {
+            var client = ScriptedChatClient<double>.Sequence(ChatResponses.Text(answer));
+            return new AgentExecutor<double>(client, tools: null, new AgentExecutorOptions { Name = name });
+        }
+
+        [Fact(Timeout = 60000)]
+        public async Task TracingAgent_RecordsEachRun()
+        {
+            var store = new InMemoryTrajectoryStore();
+            var traced = new TracingAgent<double>(Agent("writer", "Hello."), store);
+
+            var result = await traced.RunAsync(new[] { ChatMessage.User("hi") });
+
+            Assert.Equal("Hello.", result.FinalText); // behavior unchanged
+
+            var all = await store.GetAllAsync();
+            Assert.Single(all);
+            Assert.Equal("writer", all[0].AgentName);
+            Assert.Equal("Hello.", all[0].FinalText);
+            Assert.Contains(all[0].Messages, m => m.Role == ChatRole.User && m.Text == "hi");
+            Assert.Null(all[0].Reward);
+        }
+
+        [Fact(Timeout = 60000)]
+        public async Task TracingAgent_AccumulatesAcrossRuns_AndIsQueryable()
+        {
+            var store = new InMemoryTrajectoryStore();
+            await new TracingAgent<double>(Agent("a", "one"), store).RunAsync(new[] { ChatMessage.User("x") });
+            await new TracingAgent<double>(Agent("b", "two"), store).RunAsync(new[] { ChatMessage.User("y") });
+
+            Assert.Equal(2, (await store.GetAllAsync()).Count);
+
+            var onlyB = await store.QueryAsync(t => t.AgentName == "b");
+            Assert.Single(onlyB);
+            Assert.Equal("two", onlyB[0].FinalText);
+        }
+
+        [Fact(Timeout = 60000)]
+        public async Task TracingAgent_AttachesMetadata()
+        {
+            var store = new InMemoryTrajectoryStore();
+            var metadata = new Dictionary<string, string> { ["experiment"] = "exp-1" };
+            var traced = new TracingAgent<double>(Agent("a", "ok"), store, metadata);
+
+            await traced.RunAsync(new[] { ChatMessage.User("x") });
+
+            var all = await store.GetAllAsync();
+            Assert.NotNull(all[0].Metadata);
+            Assert.Equal("exp-1", all[0].Metadata["experiment"]);
+        }
+
+        [Fact(Timeout = 60000)]
+        public async Task Store_GetById_And_RewardAnnotation()
+        {
+            var store = new InMemoryTrajectoryStore();
+            var traced = new TracingAgent<double>(Agent("a", "answer"), store);
+            await traced.RunAsync(new[] { ChatMessage.User("x") });
+
+            var id = (await store.GetAllAsync())[0].Id;
+            var fetched = await store.GetAsync(id);
+            Assert.NotNull(fetched);
+
+            // An evaluator grades the trajectory; the annotation is visible on subsequent reads.
+            fetched.Reward = 0.75;
+            var again = await store.GetAsync(id);
+            Assert.NotNull(again);
+            Assert.Equal(0.75, again.Reward);
+        }
+
+        [Fact(Timeout = 60000)]
+        public async Task Store_Clear_Empties()
+        {
+            var store = new InMemoryTrajectoryStore();
+            await new TracingAgent<double>(Agent("a", "ok"), store).RunAsync(new[] { ChatMessage.User("x") });
+            await store.ClearAsync();
+            Assert.Empty(await store.GetAllAsync());
+        }
+    }
+}