admin/VolcanicAgenticCore
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(google-calendar): calendar tool read actions over Calendar v3

Browse Source
This commit is contained in:
EugeneTes
2026-09-26 20:09:53 +02:00
parent a30a4e4d03
commit edcfa690bd
5 changed files with 673 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
extensions/Volcanic.AgenticCore.Extensions.GoogleCalendar/CalendarTool.cs Normal file
View File

@@ -0,0 +1,212 @@
using System.ComponentModel;
using System.Globalization;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using Volcanic.AgenticCore.Abstractions.Json;
using Volcanic.AgenticCore.Abstractions.Tools;
namespace Volcanic.AgenticCore.Extensions.GoogleCalendar;
public sealed record CalendarArgs(
[property: Description("list, search, get, list_instances, create, update, delete or calendars")] string Action,
[property: Description("Calendar id; default primary. action=calendars lists the others")] string? CalendarId = null,
[property: Description("Window start (list, search, list_instances): RFC 3339, a local date-time or a date")] string? TimeMin = null,
[property: Description("Window end, same forms as timeMin")] string? TimeMax = null,
[property: Description("Free-text search (search only, required there)")] string? Query = null,
[property: Description("Maximum events to return; default 25, at most 250")] int? MaxResults = null,
[property: Description("list only: occurrences (default; every occurrence of recurring events) or series (recurring events once, with their RRULE)")] string? ListMode = null,
[property: Description("Event id (get, list_instances, update, delete)")] string? EventId = null,
[property: Description("update/delete of a recurring event: instance (one occurrence) or series; detected from the event when omitted")] string? Scope = null,
[property: Description("Title (create, update)")] string? Summary = null,
[property: Description("Notes (create, update)")] string? Description = null,
[property: Description("Location (create, update)")] string? Location = null,
[property: Description("YYYY-MM-DD for all day, or a date-time; without an offset it is wall time in timeZone")] string? Start = null,
[property: Description("Like start. All-day ends are exclusive. Default on create: one day / one hour after start")] string? End = null,
[property: Description("IANA zone for this event, e.g. Europe/Berlin; default the calendar's zone")] string? TimeZone = null,
[property: Description("RFC 5545 lines, e.g. [\"RRULE:FREQ=WEEKLY;BYDAY=MO,WE\"]; [] on update turns a series into a single event")] IReadOnlyList<string>? Recurrence = null);
public sealed record CalendarEventDetails(string Id, string? Summary, JsonElement? Start, JsonElement? End, string? RecurringEventId,
IReadOnlyList<string>? Recurrence, string? HtmlLink);
public sealed record CalendarResultDetails(string Action, IReadOnlyList<CalendarEventDetails> Events);
/// <summary>
/// The <c>calendar</c> tool. Always registered while the OAuth client is configured; without a token for this chat it
/// fails with the "/calendar_connect" hint. Uses only the chat's own connection (scope from the context).
/// </summary>
internal sealed partial class CalendarTool(GoogleCalendarSettings settings, GoogleCalendarConnections connections, Func<string?> currentZone) : Tool<CalendarArgs>
{
public const string ToolName = "calendar";
private const int DefaultMax = 25;
private const int MaxCap = 250;
private static readonly CultureInfo Inv = CultureInfo.InvariantCulture;
public override string Name => ToolName;
public override string Description =>
"Read and change the Google Calendar this chat connected with /calendar_connect. Actions: list, search, get, " +
"list_instances, create, update, delete, calendars. " + Rules;
public override string? PromptSnippet => "calendar: read and change this chat's Google Calendar";
public override IReadOnlyList<string> PromptGuidelines => ["calendar: " + Rules];
public override ToolExecutionMode ExecutionMode => ToolExecutionMode.Parallel;
private string Rules =>
$"Times without an offset are in {currentZone() ?? "the zone named in each result's header"}; all-day end dates are exclusive " +
"(a one-day event on 2026-09-30 ends 2026-10-01); to change one date of a recurring event, get that occurrence's id with list_instances first.";
protected override async Task<ToolResult> ExecuteAsync(CalendarArgs args, ToolInvocation invocation, CancellationToken cancellationToken)
{
var ctx = invocation.Context;
var connection = connections.For(settings, ctx.SessionManager.Scope);
var resolved = connection.ResolveTimeZone(ctx.TimeZone, ctx.Logger);
var eventZone = args.TimeZone is { Length: > 0 } requested
? ZoneIds.TryFind(requested, out var z) ? z : throw new ArgumentException($"Unknown time zone \"{requested}\". Use an IANA id such as Europe/Berlin.")
: resolved;
var run = new Run(args, new GoogleCalendarApi(connection), resolved, eventZone, CalendarTime.Header(resolved, ctx.TimeZone),
string.IsNullOrWhiteSpace(args.CalendarId) ? "primary" : args.CalendarId.Trim(), settings.Time.GetUtcNow(), cancellationToken);
var action = (args.Action ?? "").Trim().ToLowerInvariant();
return action switch
{
"list" => await ListAsync(run).ConfigureAwait(false),
"search" => await SearchAsync(run).ConfigureAwait(false),
"get" => await GetAsync(run).ConfigureAwait(false),
"list_instances" => await ListInstancesAsync(run).ConfigureAwait(false),
"calendars" => await CalendarsAsync(run).ConfigureAwait(false),
"create" or "update" or "delete" => await WriteAsync(action, run).ConfigureAwait(false),
_ => throw new ArgumentException($"Unknown action \"{args.Action}\". Use one of: list, search, get, list_instances, create, update, delete, calendars."),
};
}
/// <summary>Everything one call needs, resolved once.</summary>
private sealed record Run(CalendarArgs Args, GoogleCalendarApi Api, TimeZoneInfo Zone, TimeZoneInfo EventZone, string Header,
string CalendarId, DateTimeOffset Now, CancellationToken Ct)
{
public string EventZoneName => ZoneIds.Name(EventZone);
public int Max => Math.Clamp(Args.MaxResults ?? DefaultMax, 1, MaxCap);
public string Bound(string? given, DateTimeOffset fallback, string field) =>
given is { Length: > 0 } ? CalendarTime.ToRfc3339(given, EventZone, field) : CalendarTime.Utc(fallback);
}
private async Task<ToolResult> ListAsync(Run run)
{
var mode = (run.Args.ListMode ?? "occurrences").Trim().ToLowerInvariant();
if (mode is not ("occurrences" or "series")) throw new ArgumentException("listMode must be occurrences or series.");
var query = new List<KeyValuePair<string, string>>
{
new("timeMin", run.Bound(run.Args.TimeMin, run.Now, "timeMin")),
new("timeMax", run.Bound(run.Args.TimeMax, run.Now.AddDays(7), "timeMax")),
new("singleEvents", mode == "occurrences" ? "true" : "false"),
};
if (mode == "occurrences") query.Add(new("orderBy", "startTime"));
var items = await PageAsync(run, GoogleCalendarApi.Events(run.CalendarId), query, new CalendarCall("list", run.CalendarId)).ConfigureAwait(false);
return Events("list", run, items);
}
private async Task<ToolResult> SearchAsync(Run run)
{
if (string.IsNullOrWhiteSpace(run.Args.Query)) throw new ArgumentException("search needs query.");
var query = new List<KeyValuePair<string, string>>
{
new("q", run.Args.Query.Trim()),
new("timeMin", run.Bound(run.Args.TimeMin, run.Now.AddDays(-30), "timeMin")),
new("timeMax", run.Bound(run.Args.TimeMax, run.Now.AddDays(365), "timeMax")),
new("singleEvents", "true"),
new("orderBy", "startTime"),
};
var items = await PageAsync(run, GoogleCalendarApi.Events(run.CalendarId), query, new CalendarCall("search", run.CalendarId)).ConfigureAwait(false);
return Events("search", run, items);
}
private async Task<ToolResult> GetAsync(Run run)
{
var id = Require(run.Args.EventId, "get needs eventId.");
var ev = await run.Api.SendAsync(HttpMethod.Get, GoogleCalendarApi.Event(run.CalendarId, id), null, new CalendarCall("get", run.CalendarId, id), run.Ct).ConfigureAwait(false);
var text = run.Header + "\n" + Line(ev, run.Zone);
if (Str(ev, "description") is { Length: > 0 } description) text += "\nDescription: " + description;
return Result("get", text, [ev]);
}
private async Task<ToolResult> ListInstancesAsync(Run run)
{
var id = Require(run.Args.EventId, "list_instances needs eventId.");
var query = new List<KeyValuePair<string, string>>();
if (run.Args.TimeMin is { Length: > 0 } min) query.Add(new("timeMin", CalendarTime.ToRfc3339(min, run.EventZone, "timeMin")));
if (run.Args.TimeMax is { Length: > 0 } max) query.Add(new("timeMax", CalendarTime.ToRfc3339(max, run.EventZone, "timeMax")));
var items = await PageAsync(run, GoogleCalendarApi.Event(run.CalendarId, id) + "/instances", query, new CalendarCall("list_instances", run.CalendarId, id)).ConfigureAwait(false);
return Events("list_instances", run, items);
}
private static async Task<ToolResult> CalendarsAsync(Run run)
{
var items = await PageAsync(run, "users/me/calendarList", [], new CalendarCall("calendars", run.CalendarId)).ConfigureAwait(false);
var sb = new StringBuilder(run.Header);
foreach (var c in items)
{
sb.Append('\n').Append(Str(c, "id")).Append(" · ").Append(Str(c, "summary") ?? "(no name)")
.Append(" · ").Append(Str(c, "accessRole")).Append(" · ").Append(Str(c, "timeZone"));
if (c.TryGetProperty("primary", out var p) && p.ValueKind == JsonValueKind.True) sb.Append(" · primary");
}
return ToolResult.Text(sb.ToString(), new CalendarResultDetails("calendars", []));
}
/// <summary>Follows <c>nextPageToken</c> until <see cref="Run.Max"/> items are collected.</summary>
private static async Task<List<JsonElement>> PageAsync(Run run, string path, List<KeyValuePair<string, string>> query, CalendarCall call)
{
var items = new List<JsonElement>();
string? pageToken = null;
do
{
var pageQuery = new List<KeyValuePair<string, string>>(query) { new("maxResults", (run.Max - items.Count).ToString(Inv)) };
if (pageToken is not null) pageQuery.Add(new("pageToken", pageToken));
var page = await run.Api.SendAsync(HttpMethod.Get, path + "?" + GoogleCalendarApi.Query(pageQuery), null, call, run.Ct).ConfigureAwait(false);
if (page.TryGetProperty("items", out var list) && list.ValueKind == JsonValueKind.Array)
items.AddRange(list.EnumerateArray().Where(e => Str(e, "status") != "cancelled"));
pageToken = Str(page, "nextPageToken");
}
while (pageToken is not null && items.Count < run.Max);
return items.Take(run.Max).ToList();
}
private static ToolResult Events(string action, Run run, List<JsonElement> items)
{
var text = items.Count == 0 ? run.Header + "\nNo events." : run.Header + "\n" + string.Join("\n", items.Select(e => Line(e, run.Zone)));
return Result(action, text, items);
}
private static ToolResult Result(string action, string text, IEnumerable<JsonElement> events) =>
ToolResult.Text(text, new CalendarResultDetails(action, events.Select(Details).ToList()));
/// <summary><c>&lt;id&gt; · &lt;summary&gt; · &lt;range&gt;[ @ location][ · recurring (series=…)][ · RRULE=…]</c></summary>
internal static string Line(JsonElement ev, TimeZoneInfo zone)
{
var sb = new StringBuilder();
sb.Append(Str(ev, "id")).Append(" · ").Append(Str(ev, "summary") is { Length: > 0 } s ? s : "(no title)");
if (ev.TryGetProperty("start", out var start))
sb.Append(" · ").Append(CalendarTime.FormatRange(start, ev.TryGetProperty("end", out var end) ? end : start, zone));
if (Str(ev, "location") is { Length: > 0 } location) sb.Append(" @ ").Append(location);
if (Str(ev, "recurringEventId") is { Length: > 0 } series) sb.Append(" · recurring (series=").Append(series).Append(')');
if (Recurrence(ev)?.FirstOrDefault(r => r.StartsWith("RRULE:", StringComparison.Ordinal)) is { } rrule) sb.Append(" · RRULE=").Append(rrule[6..]);
return sb.ToString();
}
private static CalendarEventDetails Details(JsonElement ev) => new(
Str(ev, "id") ?? "", Str(ev, "summary"),
ev.TryGetProperty("start", out var s) ? s.Clone() : null, ev.TryGetProperty("end", out var e) ? e.Clone() : null,
Str(ev, "recurringEventId"), Recurrence(ev), Str(ev, "htmlLink"));
private static IReadOnlyList<string>? Recurrence(JsonElement ev) =>
ev.TryGetProperty("recurrence", out var r) && r.ValueKind == JsonValueKind.Array ? r.EnumerateArray().Select(x => x.GetString() ?? "").ToList() : null;
private static string? Str(JsonElement e, string name) =>
e.ValueKind == JsonValueKind.Object && e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() : null;
private static string Require(string? value, string message) => string.IsNullOrWhiteSpace(value) ? throw new ArgumentException(message) : value.Trim();
/// <summary>create, update, delete: Task 6.</summary>
private static Task<ToolResult> WriteAsync(string action, Run run) =>
throw new ArgumentException($"{action} is not available yet.");
}

80
extensions/Volcanic.AgenticCore.Extensions.GoogleCalendar/GoogleCalendarApi.cs Normal file
View File

@@ -0,0 +1,80 @@
using System.Net;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using Volcanic.AgenticCore.Abstractions.Json;
namespace Volcanic.AgenticCore.Extensions.GoogleCalendar;
internal readonly record struct CalendarCall(string Action, string CalendarId, string? EventId = null);
internal sealed record PrimaryCalendar(string? Account, string? TimeZone);
/// <summary>Calendar v3 over raw HTTP for one chat: bearer token from the connection, one refresh-and-retry on 401.</summary>
internal sealed class GoogleCalendarApi(GoogleCalendarConnection connection)
{
public const string BaseUrl = "https://www.googleapis.com/calendar/v3/";
public static string Events(string calendarId) => $"calendars/{Uri.EscapeDataString(calendarId)}/events";
public static string Event(string calendarId, string eventId) => $"{Events(calendarId)}/{Uri.EscapeDataString(eventId)}";
public static string Query(IEnumerable<KeyValuePair<string, string>> pairs) =>
string.Join("&", pairs.Select(p => $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));
public async Task<JsonElement> SendAsync(HttpMethod method, string pathAndQuery, JsonObject? body, CalendarCall call, CancellationToken cancellationToken)
{
var http = connection.Settings.Http;
var response = await SendOnceAsync(http, method, pathAndQuery, body,
await connection.GetAccessTokenAsync(cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
if (response.StatusCode == HttpStatusCode.Unauthorized)
{
response.Dispose();
connection.Invalidate();
response = await SendOnceAsync(http, method, pathAndQuery, body,
await connection.GetAccessTokenAsync(cancellationToken).ConfigureAwait(false), cancellationToken).ConfigureAwait(false);
}
using (response)
{
var text = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
if (response.IsSuccessStatusCode) return string.IsNullOrWhiteSpace(text) ? VolcanicJson.EmptyObject : VolcanicJson.Parse(text);
if (response.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.Gone && call.EventId is not null)
throw new GoogleCalendarException($"Event {call.EventId} not found in {call.CalendarId}.");
throw new GoogleCalendarException($"Google Calendar {call.Action} failed: {(int)response.StatusCode} {ErrorMessage(text) ?? response.ReasonPhrase}");
}
}
/// <summary>The account (primary calendar id = email) and zone, with a token that isn't stored yet.</summary>
public static async Task<PrimaryCalendar> GetPrimaryAsync(HttpClient http, string accessToken, CancellationToken cancellationToken)
{
using var response = await SendOnceAsync(http, HttpMethod.Get, "calendars/primary", null, accessToken, cancellationToken).ConfigureAwait(false);
var text = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
if (!response.IsSuccessStatusCode)
throw new GoogleCalendarException($"calendars/primary failed: {(int)response.StatusCode} {ErrorMessage(text) ?? response.ReasonPhrase}");
var json = VolcanicJson.Parse(text);
return new PrimaryCalendar(
json.TryGetProperty("id", out var id) ? id.GetString() : null,
json.TryGetProperty("timeZone", out var zone) ? zone.GetString() : null);
}
private static async Task<HttpResponseMessage> SendOnceAsync(HttpClient http, HttpMethod method, string pathAndQuery, JsonObject? body, string accessToken, CancellationToken cancellationToken)
{
using var request = new HttpRequestMessage(method, BaseUrl + pathAndQuery);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
if (body is not null) request.Content = new StringContent(body.ToJsonString(VolcanicJson.Options), Encoding.UTF8, "application/json");
return await http.SendAsync(request, cancellationToken).ConfigureAwait(false);
}
private static string? ErrorMessage(string text)
{
try
{
return JsonNode.Parse(text) is JsonObject o && o["error"] is JsonObject e && e["message"] is JsonValue m && m.TryGetValue<string>(out var s) ? s : null;
}
catch (JsonException)
{
return null;
}
}
}