Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
cfdcef7
feat: implement blob storage functionality with BlobName, BlobPolicy,…
MatthewHsu1 Sep 16, 2026
0a3b6bc
feat: implement S3 blob storage adapter and related functionality
MatthewHsu1 Sep 16, 2026
3d2e12c
feat: add blob store functionality with BlobStoreFactory, configurati…
MatthewHsu1 Sep 16, 2026
203466f
feat: implement OpenAiSandboxFilesClient and associated tests for han…
MatthewHsu1 Sep 16, 2026
017c574
feat: implement background agent handling with new providers and capt…
MatthewHsu1 Sep 16, 2026
6623793
Add Responses endpoint and related streaming functionality
MatthewHsu1 Sep 17, 2026
aaf44a5
feat: refactor various components for improved readability and perfor…
MatthewHsu1 Sep 17, 2026
6c9a348
Refactor sandbox file handling to use FileContent class
MatthewHsu1 Sep 17, 2026
139a3f5
refactor: break out configuration validator
MatthewHsu1 Sep 17, 2026
0310271
feat: implement CallTurnCommit and related transcript handling classes
MatthewHsu1 Sep 17, 2026
6c1a5d8
feat: implement CallTurnCommit and related transcript handling classes
MatthewHsu1 Sep 17, 2026
e789c30
feat: Add clock and base instructions support to agent harness and in…
MatthewHsu1 Sep 17, 2026
b97776f
feat: Add clock and base instructions support to agent harness and in…
MatthewHsu1 Sep 17, 2026
5a0b6a0
feat: Update agent instructions and enhance HostedFileCaptureProvider…
MatthewHsu1 Sep 17, 2026
c892601
Refactor Responses and Call Endpoints to Use Entry Parameter
MatthewHsu1 Sep 18, 2026
e494667
feat: Update ChatCallTitler to include system message and improve tra…
MatthewHsu1 Sep 18, 2026
74f7590
feat(tools): replace code.execute with file.publish and add shell env…
MatthewHsu1 Sep 18, 2026
44b9b44
feat(blobs): add support for TSV file type in BlobPolicy and tests
MatthewHsu1 Sep 18, 2026
e340c43
refactor: update conversation-related terminology
MatthewHsu1 Sep 19, 2026
ba56599
feat(transcript): add ReaderContent and ReaderContentFilterProvider t…
MatthewHsu1 Sep 19, 2026
a75c8c5
feat(skills): add pinned skills support and validation logic
MatthewHsu1 Sep 19, 2026
8ea471b
feat(websocket): implement FrameOutcome and FrameParser for message h…
MatthewHsu1 Sep 19, 2026
55553f0
feat(responses): refactor request handling and introduce ResponsesRun…
MatthewHsu1 Sep 19, 2026
de95bd8
feat(qdrant): implement QdrantCollectionProof for collection validati…
MatthewHsu1 Sep 19, 2026
c360c9d
feat(schema-validation): refactor ConfigurationSchemaValidator and ad…
MatthewHsu1 Sep 19, 2026
abd43ee
feat(graph): enhance ExplicitGraphRow with improved node binding and …
MatthewHsu1 Sep 19, 2026
7cd63ed
feat(validation): refactor RecordComparison method for improved opera…
MatthewHsu1 Sep 19, 2026
ede3ea5
feat(compiler): refactor tool resolution logic to streamline undeclar…
MatthewHsu1 Sep 19, 2026
994bf65
feat(auditing): enhance tool result handling by adding Attach method …
MatthewHsu1 Sep 19, 2026
3092cdf
feat(compiler): refactor graph and agent selection logic into dedicat…
MatthewHsu1 Sep 19, 2026
e19b21e
feat(compiler): introduce new compilation structures and refactor Bui…
MatthewHsu1 Sep 19, 2026
2f3cf0d
Refactor Turn Invocation Handling and Introduce ITurnAttachments Inte…
MatthewHsu1 Sep 19, 2026
950befe
feat(cache): add PassThroughHybridCache implementation and integrate …
MatthewHsu1 Sep 19, 2026
ce0fd42
feat(embeddings): implement HybridCachingEmbeddingGenerator and relat…
MatthewHsu1 Sep 19, 2026
f666d32
feat(compiler): refactor CompiledAgent construction using CompiledAge…
MatthewHsu1 Sep 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
3 changes: 3 additions & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
</ItemGroup>
<ItemGroup>
<PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.12" />
<PackageVersion Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.12" />
<PackageVersion Include="Microsoft.Extensions.Caching.Hybrid" Version="10.10.0" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.12" />
<PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.12" />
<PackageVersion Include="Microsoft.Extensions.Http" Version="10.0.2" />
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ policy:
providers:
llm:
- { kind: openai, model: gpt-5.6-luna, as: reply }
call: { kind: telnyx-relay }
conversation: { kind: telnyx-relay }
speech:
stt: { kind: telnyx-relay }
tts: { kind: telnyx-relay }
Expand All @@ -54,7 +54,9 @@ app.MapAgentCoreHost();
app.Run();
```

`AddAgentCoreHost` loads the document (`config/example.yaml` unless `AgentCore__ConfigurationPath` names another) and binds every vendor seam. `MapAgentCoreHost` serves the health check, the OpenAI-compatible Responses endpoint, and the call socket.
`AddAgentCoreHost` loads the document (`config/example.yaml` unless `AgentCore__ConfigurationPath` names another) and binds every vendor seam. `MapAgentCoreHost` serves the health check, the OpenAI-compatible Responses endpoint, and the conversation socket.
Every entry under `entries:` answers on `POST /v1/{entry}/responses` and on the conversation socket at `/v1/{entry}/call`.
An OpenAI SDK reaches one entry through its base URL alone: `base_url = https://host/v1/phone`.
A document it cannot find is a startup failure, never a silent default.

## Install
Expand Down
650 changes: 342 additions & 308 deletions config/example.yaml

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions src/AgentCore.Application/AgentCore.Application.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

<ItemGroup>
<PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Caching.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
<PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" />
<PackageReference Include="Microsoft.Agents.AI" />
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,52 +7,52 @@ namespace AgentCore.Application.Audit;
/// <summary>
/// Turns the durable facts of a call into the append-only chain of D23.
/// </summary>
internal sealed class AuditCallObserver : ICallObserver
internal sealed class AuditConversationObserver : IConversationObserver
{
private readonly IAuditSinkPort _sink;

/// <summary>Creates the observer that writes the chain.</summary>
/// <param name="sink">Where the rows go.</param>
/// <exception cref="ArgumentNullException"><paramref name="sink"/> is <see langword="null"/>.</exception>
public AuditCallObserver(IAuditSinkPort sink)
public AuditConversationObserver(IAuditSinkPort sink)
{
ArgumentNullException.ThrowIfNull(sink);

_sink = sink;
}

/// <inheritdoc />
public ValueTask OnCallEventAsync(CallEvent callEvent, CancellationToken cancellationToken)
public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(callEvent);
ArgumentNullException.ThrowIfNull(conversationEvent);

// A diagnostic-only fact took no identity, so there is no row to write and nothing to report.
if (callEvent.EventId is not { } eventId)
if (conversationEvent.EventId is not { } eventId)
{
return ValueTask.CompletedTask;
}

// The two enums are not interchangeable, and a value outside the closed set is dropped rather
// than thrown over: the turn loop pairs an identity with a stored kind, so this is unreachable
// for any event the session raises, and audit is a record of the call and never a part of it.
if (!CallEventKinds.TryGetAuditKind(callEvent.Kind, out AuditEventKind kind))
// for any event the session raises, and audit is a record of the conversation and never a part of it.
if (!ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind kind))
{
return ValueTask.CompletedTask;
}

AuditEvent auditEvent = new()
{
CallId = callEvent.CallId,
ConversationId = conversationEvent.ConversationId,
EventId = eventId,
Kind = kind,
OccurredAt = callEvent.OccurredAt,
TurnIndex = callEvent.TurnIndex,
AmendsEventId = callEvent.AmendsEventId,
Payload = callEvent.Payload,
OccurredAt = conversationEvent.OccurredAt,
TurnIndex = conversationEvent.TurnIndex,
AmendsEventId = conversationEvent.AmendsEventId,
Payload = conversationEvent.Payload,
};

// The token of the run belongs to the dispatcher, which passes CancellationToken.None: the
// enqueue belongs to the record of the call, not to a turn the caller may have cancelled.
// enqueue belongs to the record of the conversation, not to a turn the caller may have cancelled.
return _sink.AppendAsync(auditEvent, cancellationToken);
}
}
2 changes: 1 addition & 1 deletion src/AgentCore.Application/Audit/AuditSinkFactory.cs
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ public static class AuditSinkFactory
/// <summary>The built-in kind, and the one a document that names no provider gets.</summary>
public const string MemoryKind = "memory";

/// <summary>What this seam calls itself, so the shared selector writes its failures.</summary>
/// <summary>What this seam conversations itself, so the shared selector writes its failures.</summary>
private static readonly VendorSeam Seam =
new("providers.audit", "/providers/audit/kind", "options.UseAuditSinks(...)", "sinks");

Expand Down
14 changes: 7 additions & 7 deletions src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,18 @@ public IReadOnlyList<AuditEvent> Events
}

/// <summary>
/// Reads back the events of one call, oldest first.
/// Reads back the events of one conversation, oldest first.
/// </summary>
/// <param name="callId">The id of the call.</param>
/// <returns>The events of that call, in the order they arrived.</returns>
/// <exception cref="ArgumentNullException"><paramref name="callId"/> is <see langword="null"/>.</exception>
public IReadOnlyList<AuditEvent> EventsOf(string callId)
/// <param name="conversationId">The id of the conversation.</param>
/// <returns>The events of that conversation, in the order they arrived.</returns>
/// <exception cref="ArgumentNullException"><paramref name="conversationId"/> is <see langword="null"/>.</exception>
public IReadOnlyList<AuditEvent> EventsOf(string conversationId)
{
ArgumentNullException.ThrowIfNull(callId);
ArgumentNullException.ThrowIfNull(conversationId);

lock (_gate)
{
return [.. _events.Where(item => string.Equals(item.CallId, callId, StringComparison.Ordinal))];
return [.. _events.Where(item => string.Equals(item.ConversationId, conversationId, StringComparison.Ordinal))];
}
}

Expand Down
16 changes: 8 additions & 8 deletions src/AgentCore.Application/Audit/QueuedAuditSink.cs
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ public sealed class QueuedAuditSink : IAuditSinkPort, IAsyncDisposable, IDisposa
/// <summary>The number of events the queue holds before it starts dropping.</summary>
public const int DefaultCapacity = 10_000;

/// <summary>The most events the writer hands the store in one call.</summary>
/// <summary>The most events the writer hands the store in one conversation.</summary>
public const int DefaultBatchSize = 100;

/// <summary>How long <see cref="Dispose"/> waits for the drain before it gives up.</summary>
Expand Down Expand Up @@ -199,7 +199,7 @@ private async Task AppendBatchAsync(List<AuditEvent> batch)
{
await _inner.AppendManyAsync([.. batch], _stopping.Token).ConfigureAwait(false);
}
#pragma warning disable CA1031 // The store is a record of the call and never a part of it.
#pragma warning disable CA1031 // The store is a record of the conversation and never a part of it.
catch (Exception exception)
#pragma warning restore CA1031
{
Expand All @@ -219,9 +219,9 @@ private void Report(AuditEvent auditEvent)
{
try
{
Log.AuditQueueFull(_logger, auditEvent.CallId, auditEvent.EventId);
Log.AuditQueueFull(_logger, auditEvent.ConversationId, auditEvent.EventId);
}
#pragma warning disable CA1031 // A logger that refuses the report is still not a part of the call.
#pragma warning disable CA1031 // A logger that refuses the report is still not a part of the conversation.
catch (Exception)
#pragma warning restore CA1031
{
Expand All @@ -236,15 +236,15 @@ private void Report(List<AuditEvent> batch, Exception exception)
{
try
{
// One line for the batch and not one for each event. The store refused the call, so the
// fault is one fault, and the first event names the call an operator goes looking at.
// One line for the batch and not one for each event. The store refused the conversation, so the
// fault is one fault, and the first event names the conversation an operator goes looking at.
Log.AuditAppendFailed(
_logger,
batch[0].CallId,
batch[0].ConversationId,
AuditEventKinds.ToToken(batch[0].Kind),
exception);
}
#pragma warning disable CA1031 // A logger that refuses the report is still not a part of the call.
#pragma warning disable CA1031 // A logger that refuses the report is still not a part of the conversation.
catch (Exception)
#pragma warning restore CA1031
{
Expand Down
28 changes: 28 additions & 0 deletions src/AgentCore.Application/Blobs/BlobLink.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
namespace AgentCore.Application.Blobs;

/// <summary>What every store agrees on when it hands a browser a link to a blob.</summary>
public static class BlobLink
{
/// <summary>How long a link works.</summary>
public static TimeSpan Lifetime { get; } = TimeSpan.FromMinutes(15);

/// <summary>
/// The <c>Content-Disposition</c> a link serves the blob with: <c>inline</c> for what a browser
/// draws safely, <c>attachment</c> for everything else. SVG and HTML are never inline: both run
/// script under the store's origin.
/// </summary>
/// <param name="mediaType">The blob's IANA media type.</param>
/// <param name="name">The file name the browser saves it under.</param>
/// <returns>The header value.</returns>
public static string DispositionOf(string mediaType, string name)
{
ArgumentNullException.ThrowIfNull(mediaType);
ArgumentNullException.ThrowIfNull(name);

var inline = mediaType.Equals("application/pdf", StringComparison.OrdinalIgnoreCase)
|| (mediaType.StartsWith("image/", StringComparison.OrdinalIgnoreCase)
&& !mediaType.Contains("svg", StringComparison.OrdinalIgnoreCase));

return (inline ? "inline" : "attachment") + "; filename*=UTF-8''" + Uri.EscapeDataString(name);
}
}
41 changes: 41 additions & 0 deletions src/AgentCore.Application/Blobs/BlobMediaTypes.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
namespace AgentCore.Application.Blobs;

/// <summary>The media type a file name implies, one entry per <see cref="BlobPolicy.DefaultExtensions"/>.</summary>
internal static class BlobMediaTypes
{
/// <summary>The type for a name whose extension is not listed. A browser saves it rather than showing it.</summary>
public const string Fallback = "application/octet-stream";

private static readonly Dictionary<string, string> ByExtension = new(StringComparer.OrdinalIgnoreCase)
{
["png"] = "image/png",
["jpg"] = "image/jpeg",
["jpeg"] = "image/jpeg",
["gif"] = "image/gif",
["webp"] = "image/webp",
["pdf"] = "application/pdf",
["csv"] = "text/csv",
["tsv"] = "text/tab-separated-values",
["txt"] = "text/plain",
["md"] = "text/markdown",
["json"] = "application/json",
["zip"] = "application/zip",
["xlsx"] = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
["docx"] = "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
["pptx"] = "application/vnd.openxmlformats-officedocument.presentationml.presentation",
};

/// <summary>Reads the media type off a file name's extension.</summary>
/// <param name="name">The file name.</param>
/// <returns>The IANA media type, or <see cref="Fallback"/> when the extension is not listed.</returns>
public static string Of(string name)
{
ArgumentNullException.ThrowIfNull(name);

var extension = Path.GetExtension(name).TrimStart('.');

return extension.Length > 0 && ByExtension.TryGetValue(extension, out var mediaType)
? mediaType
: Fallback;
}
}
36 changes: 36 additions & 0 deletions src/AgentCore.Application/Blobs/BlobName.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
using System.Text;

namespace AgentCore.Application.Blobs;

/// <summary>
/// The one shape a blob name may take. A name is a key, never a path.
/// </summary>
public static class BlobName
{
/// <summary>The longest name, in UTF-8 bytes, that every backing store accepts.</summary>
public const int MaxBytes = 255;

/// <summary>Says whether a name is safe to use as a key.</summary>
/// <param name="name">What the model or the caller wrote.</param>
/// <returns><see langword="true"/> when the name is not empty, holds no path separator, no <c>..</c>,
/// no control character, and fits in <see cref="MaxBytes"/>.</returns>
public static bool IsSafe(string? name)
{
if (string.IsNullOrWhiteSpace(name))
{
return false;
}

if (name.Contains("..", StringComparison.Ordinal))
{
return false;
}

if (name.Any(c => c is '/' or '\\' || char.IsControl(c)))
{
return false;
}

return Encoding.UTF8.GetByteCount(name) <= MaxBytes;
}
}
68 changes: 68 additions & 0 deletions src/AgentCore.Application/Blobs/BlobPolicy.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
namespace AgentCore.Application.Blobs;

/// <summary>
/// What a captured sandbox file must satisfy before it is stored.
/// </summary>
public sealed class BlobPolicy
{
/// <summary>The cap a sandbox file must fit under. 10 MB.</summary>
public const long DefaultMaxBytes = 10L * 1024 * 1024;

/// <summary>
/// The extensions stored by default: images, PDF, plain data and Office files. Never
/// <c>html</c>, <c>svg</c> or <c>xml</c>: a presigned link serves those as a live page from
/// the bucket, so a model-written file could pose as one of the operator's own.
/// </summary>
public static readonly IReadOnlySet<string> DefaultExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
"png", "jpg", "jpeg", "gif", "webp", "pdf", "csv", "tsv", "txt", "md", "json", "zip", "xlsx", "docx", "pptx",
};

/// <summary>The policy the harness uses when the document names none.</summary>
public static BlobPolicy Default { get; } = new(DefaultMaxBytes, DefaultExtensions);

/// <summary>Makes a policy.</summary>
/// <param name="maxBytes">The largest file stored. Must be positive.</param>
/// <param name="allowedExtensions">Extensions stored, without the dot. Case does not matter.</param>
public BlobPolicy(long maxBytes, IEnumerable<string> allowedExtensions)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxBytes);
ArgumentNullException.ThrowIfNull(allowedExtensions);

MaxBytes = maxBytes;
AllowedExtensions = new HashSet<string>(allowedExtensions, StringComparer.OrdinalIgnoreCase);
}

/// <summary>Gets the largest file stored, in bytes.</summary>
public long MaxBytes { get; }

/// <summary>Gets the extensions stored, without the dot.</summary>
public IReadOnlySet<string> AllowedExtensions { get; }

/// <summary>Says why a file is refused, or that it is not.</summary>
/// <param name="name">The file's name, already normalised by <see cref="BlobName"/>.</param>
/// <param name="length">The file's size in bytes.</param>
/// <returns>A short reason fit for a log line, or <see langword="null"/> when the file may be stored.</returns>
public string? WhyRefused(string name, long length)
{
ArgumentNullException.ThrowIfNull(name);

if (length < 0 || length > MaxBytes)
{
return $"size {length} is outside 0..{MaxBytes} bytes";
}

var dot = name.LastIndexOf('.');

if (dot < 0 || dot == name.Length - 1)
{
return "no extension";
}

var extension = name[(dot + 1)..];

return AllowedExtensions.Contains(extension)
? null
: $"extension '{extension}' is not allowed";
}
}
14 changes: 14 additions & 0 deletions src/AgentCore.Application/Blobs/BlobRead.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
namespace AgentCore.Application.Blobs;

/// <summary>One stored blob, opened for reading. Dispose it to release the stream.</summary>
/// <param name="MediaType">The IANA media type, such as <c>image/png</c>.</param>
/// <param name="Length">How many bytes <paramref name="Content"/> holds.</param>
/// <param name="Content">The bytes, positioned at the start.</param>
public sealed record BlobRead(
string MediaType,
long Length,
Stream Content) : IAsyncDisposable
{
/// <inheritdoc />
public ValueTask DisposeAsync() => Content.DisposeAsync();
}
12 changes: 12 additions & 0 deletions src/AgentCore.Application/Blobs/BlobRef.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
namespace AgentCore.Application.Blobs;

/// <summary>One stored blob, apart from its bytes.</summary>
/// <param name="OwnerId">Who wrote it.</param>
/// <param name="Name">The name it is stored under.</param>
/// <param name="MediaType">The IANA media type, such as <c>image/png</c>.</param>
/// <param name="Length">How many bytes it holds.</param>
public sealed record BlobRef(
string OwnerId,
string Name,
string MediaType,
long Length);
Loading
Loading