Universal.Operative.Sdk.Scheduling 1.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, whether or not the host process is running when it fires.

• ScheduleCreateTool / ScheduleListTool / ScheduleCancelTool (SchedulerTools.Create) — the model-facing surface. Backed by a shared IScheduleStore.
• InMemoryScheduleStore / FileScheduleStore + SchedulerRuntime — the common case: schedules that only need to survive while this process (or one already supervised to restart, e.g. a systemd service or Windows Service) is running. SchedulerRuntime ticks the store and fires due schedules through an IScheduleTrigger.
• ScheduleTriggerHandler — turns a fired schedule into a submitted IOperative message. The same seam both the in-process runtime and any out-of-process trigger (an OS-scheduled task hitting a host's loopback HTTP endpoint) resolve to.
• IDurableScheduleBackend (WindowsTaskSchedulerBackend, SystemdTimerBackend, CrontabBackend) — for schedules that must survive the host process itself not running at all: registers with the OS's own scheduler. The OS-level entry 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 argument.

How to Use

Installation

dotnet add package Universal.Operative.Sdk.Scheduling

The common case: in-process, no restart needed

using Universal.Operative.Sdk.Scheduling;

var setup = new SchedulingSetup(); // fresh InMemoryScheduleStore; pass a FileScheduleStore(path) to survive a restart

IOperative operative = engineBuilder
    .AddBaselineTools()
    .AddSchedulerTools(setup)
    .BuildOperative(conversation);

SchedulerRuntime runtime = operative.StartScheduler(setup);

Two calls, not one, because of a real chicken/egg: AddSchedulerTools registers the tools before the engine (and so the IOperative) exists, but firing a schedule needs that same IOperative to submit into -- a tool can't close over something built after it. StartScheduler is the second half, wired once the operative is real. Construct one SchedulingSetup and pass that same instance to both calls; StartScheduler checks this and throws immediately if it's ever given a setup AddSchedulerTools never saw, rather than silently watching a store nothing writes to.

Durable, host-not-running-at-all case

IDurableScheduleBackend backend = OperatingSystem.IsWindows() ? new WindowsTaskSchedulerBackend()
    : OperatingSystem.IsLinux() ? new SystemdTimerBackend() // or new CrontabBackend()
    : throw new PlatformNotSupportedException();

var setup = new SchedulingSetup(durableBackend: backend);

IOperative operative = engineBuilder.AddSchedulerTools(setup).BuildOperative(conversation);

TriggerCommand trigger = TriggerCommands.Curl(new Uri("http://127.0.0.1:5099/schedule/trigger"), sharedSecret: "...");
await backend.RegisterAsync(schedule, trigger);

The host is responsible for the loopback HTTP endpoint itself and for calling ScheduleTriggerHandler.FireAsync when it receives a hit — this package doesn't take a web-framework dependency to provide one. TriggerCommand isn't curl-specific either: TriggerCommands.Curl(...) is just a convenience factory — construct one directly (any executable + arguments) to fire something else entirely.

Passing a durableBackend on SchedulingSetup gets you, for free:

• ScheduleCancel unregisters both places — the logical record and the OS-level registration, not just the former.
• ScheduleList reports durablyRegistered: true/false per schedule, plus an orphanedDurableIds array for OS-level registrations with no matching schedule left in the store (e.g. an InMemoryScheduleStore that didn't survive a restart the OS registration did) — these will still fire, hitting the trigger endpoint with an id nothing can resolve a prompt for.

Every backend's naming is overridable via its constructor (WindowsTaskSchedulerBackend(taskFolder:), SystemdTimerBackend(unitDirectory:, unitPrefix:), CrontabBackend(markerPrefix:)) — set these if more than one app on the same machine uses this package, so their registrations, and their ListAsync results, don't collide.

License

Free for noncommercial use under the Universal.Operative Noncommercial License. Source is closed; commercial use requires a separate license from Andrew Ong.