recurring-tasks

name	recurring-tasks
description	Use when the user asks to set up or manage a recurring AI job. Do not use for one-off commands or generic scheduler questions.

Generated from blueprint.yaml. Do not edit this block by hand.

Executable Interfaces:

Call famulus.invoke with required caller (caller skill), interface, version, and arguments; optional dry_run defaults to false. Compact uses ordered positionals plus an option mapping; ordered raw argv uses positionals: [] plus every argv token in list options. Never mix forms.

• recurring-tasks._rtx.interface.scripts-disable — Disable a job by setting enabled: false in jobs.yaml and syncing native scheduler entries.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": ["name"], "stdin": null} Required options: []; positional arity: 1..1; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-enable — Enable a job by setting enabled: true in jobs.yaml and syncing native scheduler entries.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": ["name"], "stdin": null} Required options: []; positional arity: 1..1; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-healthcheck — Run pre-flight and per-job health checks for all enabled recurring tasks and return nonzero when any check fails.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": [], "stdin": null} Required options: []; positional arity: 0..0; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-remove-context — Remove the shared native set only when the selected recurring config root is its current owner.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": [], "stdin": null} Required options: []; positional arity: 0..0; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-setup — Capture the selected Python and plugin root, initialize recurring-owned state without default jobs, and reconcile the shared scheduler set.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--canonical-python": "FILE", "--plugin-root": "DIR"}, "positionals": [], "stdin": null} Required options: ["--canonical-python", "--plugin-root"]; positional arity: 0..0; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-status — List active recurring scheduler entries, next fire times, and service status.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": [], "stdin": null} Required options: []; positional arity: 0..0; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-sync — Regenerate native scheduler entries from jobs.yaml.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": [], "stdin": null} Required options: []; positional arity: 0..0; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-test — Trigger a job immediately through the native scheduler, then wait (bounded) for its run record and report whether the job actually succeeded.
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {}, "positionals": ["name"], "stdin": null} Required options: []; positional arity: 1..1; stdin: forbidden
• recurring-tasks._rtx.interface.scripts-view-logs — Tail the run log for a job (default 50 lines).
  • Caller: recurring-tasks
  • Version: 1
  • Alternative: owner Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--lines": "N"}, "positionals": ["job-name"], "stdin": null} Required options: []; positional arity: 1..1; stdin: forbidden

Instruction Interfaces:

These are LLM-readable instruction surfaces. Read and follow them directly; do not invoke the MCP server for them.

• setup-python-environment.interface.repair-selected-packages@1 — Repair the core or one caller-owned package declaration in the exact selected Python environment without MCP.

Recurring Tasks

Manage explicitly authorized recurring AI jobs through recurring-owned durable state and the native per-user scheduler. Making this skill available does not create, enable, or run a job.

Context and ownership

Use the host-loaded setup-python-environment.interface.repair-selected-packages procedure for feature recurring-tasks and the exact deduplicated declaration ["PyYAML"]. Run its complete initial literal-python fingerprint, pip/installability and target-writability checks, repair and dry-run steps, and final fingerprint. Require the final fingerprint to be byte-equal to the initial fingerprint. Retain its canonical absolute executable; do not select or repair another Python.

Resolve the current selected plugin root from the host-loaded location of this skill. Invoke scripts-setup with that root and the retained canonical Python. Setup captures both values in the validated recurring-owned descriptor. A plugin-cache path change is repaired by rerunning setup; there is no generic updater or installer-runtime indirection.

All feature contexts share one native scheduler set for the host account. Setup, sync, enable, or disable replaces that complete set from the selected durable jobs configuration. The canonical absolute durable recurring config root is the owner_id; the last successful reconciliation owns the set. A failed reconciliation cannot claim ownership, and non-owner removal leaves the shared set unchanged.

Operations

Use the generated interfaces as follows:

• scripts-setup creates or refreshes recurring-owned integration and replaces the shared scheduler set and healthcheck sentinel where supported. First setup creates an empty jobs file unless validated user or legacy jobs exist.
• scripts-sync replaces the shared scheduler set from enabled definitions.
• scripts-enable and scripts-disable change authorization for one job and reconcile its registration.
• scripts-status reports configured state and the shared native set.
• scripts-test triggers one job and waits, bounded, for a fresh outcome record; never treat scheduler trigger acceptance as job success.
• scripts-view-logs reads the selected durable context's bounded job log.
• scripts-healthcheck checks descriptor, source, scheduler, registration, activity, and outcome health. On platforms without the independent sentinel, invoke it on demand.
• scripts-remove-context removes shared registrations only when the selected durable config root is their owner, while preserving definitions and history.

Before invoking an interface, read the selected job and current status needed for its arguments. Report a failed operation without claiming scheduler state changed.

Job definitions

Each job has a unique name, description, command, restricted cron schedule, enabled flag, and optional success contract. The platform-neutral job schema does not promise one identical Cartesian cron grammar across managed hosts.

Linux accepts exactly five fields. Minute and hour each accept *, */N for positive N, or one bounded bare integer (minute 0 through 59, hour 0 through 23); day-of-month and month must each be *; weekday accepts * or one bare integer from 0 through 7 (0 and 7 are Sunday). Ranges and comma lists are rejected.

macOS currently supports that same component-wise five-field subset, including the Cartesian combinations of accepted minute and hour values. Windows supports all-wildcard schedules; */N * * * * for positive N; M * * * * for a bounded minute M; and M H * * D for bounded M, bounded hour H, and an optional weekday D (* or 0 through 7). It does not support stepped or wildcard minutes combined with a fixed hour or weekday, nor a stepped hour.

A missing success contract means exit-code-only success. If the job writes its own status, require the expected inner status. Tolerated transient failures must match both an explicitly allowed exit code and the current run's output pattern.

Review the command, working directory, connected accounts, and intended writes before enabling a job. Enabled jobs run without an interactive approval prompt and may run outside the host sandbox; disabling a job ends that continuing authorization.

Do not adopt presets merely because recurring setup was selected. Install a preset only after explicit user selection. Preserve validated user-authored and migrated legacy jobs, including a pre-existing legacy due-wakeup entry; do not replace them from default_jobs.yaml. Recurring setup does not install interactive launchers, wakeup integration, or unrelated optional packages.

Execution and health invariants

The scheduler invokes the recurring executor with ordered shell-free argv using the captured canonical Python, selected plugin root, descriptor, job, and log roots. Paths containing spaces remain one argument. Do not introduce the former runtime pointer, resolver coupling, legacy resolver entry point, Python discovery, or a generic runtime wrapper. invoke-skill remains the intentional virtual job token and enters the existing agent-command path.

The executor alone decides success from the process exit code, current-run status, and declared success contract. It records one outcome with a unique run ID. Test and healthcheck read that outcome; neither invents a second success definition or substitutes log modification time.

Sync and healthcheck use the same renderer. If a run is active, healthcheck applies the job timeout; otherwise it verifies registration activity and a fresh successful outcome. Logs rotate after the configured cap with one prior generation retained.

If the captured source disappears, report the exact source failure. Restore the selected plugin or rerun recurring setup, then run scripts-sync. Do not rewrite native registrations or the schedule descriptor by hand.

Removal

The general installer does not own recurring setup, diagnosis, repair, or teardown. Use scripts-remove-context for owner-checked native teardown. Removal preserves recurring configuration and history; delete those only in a separately authorized data-retention operation.