Universal.Operative.Sdk.Scheduling
4.0.0
dotnet add package Universal.Operative.Sdk.Scheduling --version 4.0.0
NuGet\Install-Package Universal.Operative.Sdk.Scheduling -Version 4.0.0
<PackageReference Include="Universal.Operative.Sdk.Scheduling" Version="4.0.0" />
<PackageVersion Include="Universal.Operative.Sdk.Scheduling" Version="4.0.0" />
<PackageReference Include="Universal.Operative.Sdk.Scheduling" />
paket add Universal.Operative.Sdk.Scheduling --version 4.0.0
#r "nuget: Universal.Operative.Sdk.Scheduling, 4.0.0"
#:package Universal.Operative.Sdk.Scheduling@4.0.0
#addin nuget:?package=Universal.Operative.Sdk.Scheduling&version=4.0.0
#tool nuget:?package=Universal.Operative.Sdk.Scheduling&version=4.0.0
About
Universal.Operative.Sdk.Scheduling schedules a prompt to be enqueued into an Universal.Operative.Sdk IOperative at a future time, either once or on a recurring cron schedule — durably: its registration survives the creating process. The trigger target must be running or independently activated when delivery is attempted; a curl command does not start an unavailable HTTP host. There's no in-process/non-durable mode — a schedule with nowhere to durably register would never fire under any circumstances, so this SDK doesn't offer that as an option.
ScheduleService— create/list/cancel/fire logic (validate cron, write the store, durably register/unregister, roll back on failure; resolve a fired id to its prompt, fire it, then stamp or fully cancel) shared by the model-facing tools below, any HTTP admin surface a host wants to mount over the same store, and the host's own trigger endpoint — one definition of each operation, not one per caller.ScheduleCreateTool/ScheduleListTool/ScheduleCancelTool(SchedulerTools.Create) — the model-facing surface, backed by a sharedScheduleService.FileScheduleStore— persists schedules (and their prompt text) as JSON on disk, so they're still there after this process restarts. Bring your ownIScheduleStoreimplementation (e.g. database-backed) for anything beyond one supervised instance reading one file; ids default to a 32-character hex GUID, overridable via its constructor'sidGenerator.ScheduleTriggerHandler— turns a fired schedule's prompt into a submittedIOperativemessage. Pass it toScheduleService.FireAsyncfrom the host's own trigger endpoint (an OS-scheduled task, or a remote dispatcher, hitting a host's own HTTP endpoint) whenever it fires. Its optionalcontextFactorybuilds the turn'sITurnContextfrom the firing schedule's id, so a host that stamps every other channel's turns with a channel-specific context (who sent this, from where) can do the same for a scheduled one instead of leaving it context-free.IDurableScheduleBackend— registers a schedule with an OS scheduler or remote dispatcher that invokes the configured trigger target.WindowsTaskSchedulerBackend/SystemdTimerBackend/CrontabBackendregister with the OS's own scheduler (needs a locally-reachable Task Scheduler/systemd/cron);HttpDurableScheduleBackendregisters against a remote HTTP dispatcher instead, for hosts with no local OS scheduler reachable at all (e.g. a sandboxed PaaS container). Either way, the durable registration only ever carries the schedule's opaque id, never its prompt text — the trigger endpoint resolves id → prompt from the store at fire time, so a schedule's content never has to be safe as a shell/command-line/unit-file/HTTP-payload argument beyond that id.
How to Use
Installation
dotnet add package Universal.Operative.Sdk.Scheduling
Wiring it up
using Universal.Operative.Sdk;
using Universal.Operative.Sdk.Discrete;
using Universal.Operative.Sdk.Scheduling;
TriggerCommand trigger = TriggerCommands.Curl(new Uri("http://127.0.0.1:5099/schedule/trigger"), sharedSecret: "...");
IDurableScheduleBackend backend = IDurableScheduleBackend.ForCurrentPlatform(trigger); // Windows/Linux/other -> the matching backend, pre-wired to trigger
ScheduleService scheduleService = new ScheduleService(new FileScheduleStore(path), backend);
IOperative operative = engineBuilder.AddBaselineToolSet().AddSchedulerTools(scheduleService).BuildOperative(conversation);
ScheduleCreate writes to the store and then registers with the backend. If registration fails or is canceled, it attempts store cleanup with an independent 30-second timeout. This is compensating cleanup, not a transaction across the store and scheduler: a backend may have partially committed, and cleanup can fail. Failure results report cleanup problems; cancellation still propagates, with ScheduleId and any ScheduleCleanupException retained in the exception's Data. Use ScheduleList to identify missing or orphaned registrations and reconcile them through the store/backend before retrying. Every IDurableScheduleBackend is fully configured at construction time — RegisterAsync needs nothing beyond the schedule itself, so there's no separate "trigger template" to keep in sync with the host.
The host is responsible for the HTTP endpoint itself — this package doesn't take a web-framework dependency to provide one — but not for the logic behind it. Reuse the same ScheduleService once the operative exists (since ScheduleTriggerHandler wraps it) and hand the endpoint's id straight to FireAsync, which resolves it to a prompt, fires it, and applies the bookkeeping firing implies (stamps LastFiredAt for a recurring schedule, or fully cancels — store and durable backend — a one-shot one):
ScheduleTriggerHandler triggerHandler = new ScheduleTriggerHandler(operative, contextFactory: scheduleId => new MyTurnContext(source: "Schedule", id: scheduleId));
// In the endpoint handler, given the id from the URL/payload:
ScheduleFireResult result = await scheduleService.FireAsync(id, triggerHandler);
if (!result.Found)
{
Console.WriteLine("The schedule was already fired or canceled.");
}
contextFactory is optional — omit it for a bare TurnContext (no attribution). The host owns endpoint authentication, supervision or activation, and delivery policy. OS scheduler and dispatcher behavior determines missed-run delivery; registration alone does not guarantee catch-up after an outage. Fire delivery can be at least once, and concurrent deliveries can both submit a one-shot prompt before cleanup completes; consumers needing deduplication must coordinate delivery in their own store/trigger.
TriggerCommand isn't curl-specific either: TriggerCommands.Curl(...) is just a convenience factory — construct one directly (any executable + arguments) to fire something else entirely. For a URL shape other than Curl's own {endpointBaseUrl}/{id} default (the id in a query string, say), pass a template string instead: TriggerCommands.Curl("https://host.example.net/hooks/fire?scheduleId={id}", sharedSecret: "...") — it must contain {id} somewhere, or every schedule would fire the exact same literal URL.
No locally-reachable OS scheduler (a sandboxed PaaS container)
Swap IDurableScheduleBackend.ForCurrentPlatform(trigger) for HttpDurableScheduleBackend, which registers against a remote HTTP dispatcher over plain HTTPS instead of shelling out to a local schtasks/systemctl/crontab:
using HttpDurableScheduleBackend backend = new HttpDurableScheduleBackend(dispatcherBaseUrl: new Uri("https://scheduling-dispatcher.example.net"), dispatcherApiKey: dispatcherApiKey, operativeSlug: "my-operative", triggerUrlTemplate: "https://my-operative.example.net/schedule/{id}", triggerSecret: triggerSecret);
This backend already knows where (and with what secret) to reach this operative from its own constructor, so it needs no TriggerCommand at all — triggerUrlTemplate plays the same role, resolved to a concrete per-schedule URL ({id} substituted for the firing schedule's own id) before it's ever sent to the dispatcher, so the id can go anywhere in the URL — a path segment, a query string — and the dispatcher only ever sees a literal URL to POST to, never a placeholder. It uses the same CronExpression parser as the model-facing tools; CanExpress(cron, recurring) checks that shared syntax rather than an OS-specific translation.
What a durable backend gets you
ScheduleCancelunregisters both places — the logical record and the durable registration, not just the former.ScheduleListreportsdurablyRegistered: true/falseper schedule, plus anorphanedDurableIdsarray for durable registrations with no matching schedule left in the store (e.g. a store that didn't survive a restart the durable registration did) — these will still fire, hitting the trigger endpoint with an id the store no longer has a prompt for;ScheduleService.FireAsyncreports that asFound: falserather than throwing, but the durable registration itself is still there and worth cleaning up.
Every OS-level backend takes its TriggerCommand as the first constructor argument, with naming overridable via the same constructor (WindowsTaskSchedulerBackend(trigger, taskFolder:), SystemdTimerBackend(trigger, unitDirectory:, unitPrefix:), CrontabBackend(trigger, markerPrefix:)) — set the naming override if more than one app on the same machine uses this package, so their registrations, and their ListAsync results, don't collide. Constructing one directly on the wrong OS throws PlatformNotSupportedException immediately rather than failing later at RegisterAsync.
Verification and deployment prerequisites
Cron is interpreted in the scheduling host's local time zone. A remote dispatcher must use the same regional time-zone rules; its registration protocol currently carries no time-zone identity. Use a durable shared IScheduleStore for multiple host processes. FileScheduleStore serializes access only within one instance; do not share its file among concurrent instances or processes. Corrupt store JSON fails without replacing the original file.
Local scheduler integration tests are classified LiveAdministrative and require OPERATIVE_RUN_ISOLATED_SCHEDULER_TESTS=1 in a disposable isolated account. Routine verification excludes them: dotnet test Universal.Operative.Sdk.Scheduling.Tests --filter "TestCategory!=LiveAdministrative". Windows minute intervals are anchored at midnight and only steps dividing 60 minutes or 24 hours are accepted; unsupported cron shapes fail instead of being approximated. Systemd trigger arguments reject control characters and preserve literal percent signs, dollars, backslashes and quotes.
License
Free for noncommercial use under the Universal.Operative Noncommercial License. Source is closed; commercial use requires a separate license from Andrew Ong.
Migration
Create one ScheduleService(store, backend), pass it to AddSchedulerTools(service) or SchedulerTools.Create(service), and reuse it for FireAsync. The former SchedulingSetup/IsWired marker is removed: service identity expresses the shared workflow directly. Unsupported cron expressions are rejected before store mutation. Failed creation exposes original Failure, secondary CleanupFailure, and ScheduleId to hosts; cancel/fire results retain an unregister Failure. Exceptions are excluded from JSON serialization. Cancellation still propagates. Crontab mutations serialize within one backend instance; coordinate separate instances/processes externally.
Backend implementations now expose CanExpress(cron, recurring). Capability checks distinguish recurring calendar translation from an exact one-shot instant, so valid one-shot requests remain supported even when the full recurring pattern cannot be translated. The service checks this before writing the store. Native command failures retain Executable, Arguments, ExitCode, StandardOutput, and StandardError in the original exception Data; arguments are host diagnostics and are not copied into the model-facing failure message.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Universal.Common.Cron (>= 1.0.0)
- Universal.Common.Net.Http (>= 5.2.0)
- Universal.Operative.Sdk.Discrete (>= 4.0.0)
-
net11.0
- Universal.Common.Cron (>= 1.0.0)
- Universal.Common.Net.Http (>= 5.2.0)
- Universal.Operative.Sdk.Discrete (>= 4.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 4.0.0 | 86 | 11/18/2026 |
| 3.1.1 | 91 | 11/16/2026 |
| 3.1.0 | 114 | 11/11/2026 |
| 3.0.2 | 118 | 11/10/2026 |
| 3.0.1 | 198 | 9/7/2026 |
| 3.0.0 | 150 | 9/1/2026 |
| 2.3.0 | 142 | 8/26/2026 |
| 2.2.0 | 153 | 8/12/2026 |
| 2.1.1 | 155 | 8/5/2026 |
| 2.1.0 | 134 | 7/29/2026 |
| 2.0.0 | 140 | 7/29/2026 |
| 1.2.0 | 127 | 7/28/2026 |
| 1.1.0 | 129 | 7/28/2026 |
| 1.0.0 | 131 | 7/27/2026 |
Targets .NET 10 and .NET 11; removes .NET 8 support. Removes SchedulingSetup and IsWired; share one ScheduleService across registration and firing. Backend capability checks now take CanExpress(cron, recurring). ScheduleListItem uses named properties. Failed creation and cancellation retain cleanup and native command failure context.