Skip to content

feat(manifest): give scheduled tasks a default schedule - #61

Merged
Quick104 merged 6 commits into
mainfrom
feat/scheduled-task-default-trigger
Nov 18, 2026
Merged

Quick104 merged 6 commits into
mainfrom
feat/scheduled-task-default-trigger

Conversation

@Quick104

@Quick104 Quick104 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem

A plugin's scheduled task runs once at each host start until an administrator binds a schedule
through the task bindings API, so plugins document API calls for administrators to make by hand.

Approach

A scheduled_task.v1 capability can declare a default_trigger (ScheduledTaskDescriptor,
capability descriptor field 14): interval, daily, weekly or startup. The host uses it until an
administrator sets a schedule. The validator checks the fields of the known trigger types, rejects
intervals under 60 seconds, and accepts types it doesn't know, which a host replaces with its own
default. docs/scheduled-task.md documents it, including three points plugin authors rely on:
time_of_day is in the Silo server process's time zone (UTC in the default container), each firing
runs on one API server, and startup means once when Silo starts. The host side of the last two is
Silo-Server/silo-server#3551 and the stacked single-run change. Since every install shares the
same default, the doc also asks tasks that call outside services to add their own jitter.

Compatibility and release

Additive. A plugin that declares default_trigger needs a Silo server that includes
Silo-Server/silo-server#2502: an older server refuses to install it from a bare binary and won't
start it from an archive, because it doesn't know the descriptor field. A server that drops the
descriptor keeps running the task at startup.

Related changes

Validation

  • go test ./..., go vet ./... and every example build: pass.
  • gofmt -l . lists only pkg/pluginsdk/runtime/scan_source_test.go, which is unformatted on main
    and not touched here.
  • Regenerating the protobuf code with the repo's buf leaves it unchanged. make proto itself stops
    at its protoc check on this machine, though generation doesn't use protoc.
  • On shared dev, the scheduled-task example registered on its default (daily 03:00) without a
    restart, and went back to it when its binding's trigger was cleared.

Evidence

Evidence: https://evidence.siloserver.org/r/silo-plugin-sdk/pr-61/

AI Disclosure

  • Harness: Claude Code, run from T3 Code
  • Tool(s): Claude Code (implementation); Codex CLI (independent review)
  • Model(s): claude-opus-5-5 (implementation); gpt-6.1-sol (review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: the same Codex (gpt-6.1-sol) review; no findings on this change.
  • Later review (2026-11-18): Claude Code (claude-fable-5-2) rebased this onto main and applied the fixes; claude-opus-5-5 and gpt-6.2-sol (Codex) each reviewed it independently. gpt-6.2-sol found that a default interval too long for a host timer passed validation; it is refused now.

🤖 Generated with Claude Code

Note

Add default schedule support to scheduled-task capabilities

  • Adds scheduled_task (protobuf field 14) to CapabilityDescriptor, with ScheduledTaskDescriptor and ScheduledTaskTrigger messages in common.proto
  • DecodeCapability and capabilityMetadata in convert.go now round-trip the typed descriptor, preserving unknown fields
  • New validateScheduledTaskCapability in scheduled_task.go enforces trigger types, interval bounds, weekly day range, and HH:MM time format; unknown non-empty trigger types pass
  • Updates the hello-scheduled-task example to declare a default daily trigger at 03:00
  • Behavioral Change: manifest.Validate now rejects scheduled-task descriptors with missing or invalid triggers, and rejects descriptors attached to other capability types

Macroscope summarized ba04b73.

@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

The SDK adds scheduled-task capability metadata, manifest validation, and conversion support. Documentation describes trigger behavior and host compatibility. The example manifest configures a daily trigger at 03:00.

Changes: Scheduled task capability

Layer / File(s) Summary
Define and validate scheduled-task metadata
proto/silo/plugin/v1/common.proto, pkg/pluginsdk/manifest/...
The protobuf contract adds scheduled-task descriptors and trigger fields. Manifest validation checks capability type, required trigger type, interval minimum, weekly day bounds, and daily or weekly time format. Tests cover valid and invalid trigger data.
Convert scheduled-task metadata
pkg/pluginsdk/convert/...
Capability conversion serializes and decodes scheduled-task descriptors. A round-trip test checks decoding when stored metadata contains unknown fields.
Document and demonstrate scheduled-task configuration
docs/scheduled-task.md, examples/hello-scheduled-task/..., README.md
The documentation describes trigger behavior and compatibility notes. The example declares a daily trigger at 03:00, and the root README links to the documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Merge Risk: Low · up to c9fba

This adds an optional default schedule for scheduled-task plugins and validates it. The example README does not warn that older Silo hosts refuse to install the example because its manifest now includes the new descriptor, so someone could hit an unexplained install failure. The code changes are additive and low risk, and the README warning is a small fix.

Security architecture risk: Minimal · up to c9fba

The inspected changes add optional scheduling defaults without establishing a security-control bypass or changing execution privileges. Validation constrains recognized triggers, and compatibility limitations are documented. Administrator override and distributed execution guarantees depend on the separate host implementation and were not verified here.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The immediate changed authority is plugin-authored default timing for an installed task capability. The descriptor supplies no credentials, execution principal or target endpoint, and conversion preserves the record's type and ID. Downstream exposure depends on host scheduling and the task's existing privileges; tenant isolation and task-specific external effects were not established by the available source.

Trust Boundaries and Controls

  • observed — The normal manifest loader validates decoded plugin input. A scheduled-task descriptor is rejected on another capability type; a supplied trigger requires a nonempty type. Recognized interval triggers require at least 60 seconds, daily and weekly triggers require a valid 24-hour HH:MM value, and weekly weekdays must be 0 through 6. Unknown nonempty trigger types are intentionally accepted rather than treated as validated host behavior.
  • observed — Stored-metadata decoding intentionally discards unknown fields under an existing cross-version policy. The new round-trip test checks preservation of known scheduled-task values despite unknown descriptor and trigger fields. This does not verify host validation before scheduling or preservation of unknown fields if an older consumer later writes metadata back.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: scheduled tasks gain a default schedule via a manifest descriptor. The changeset adds a default_trigger for scheduled_task.v1 capabilities in the protobuf schema, mani…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description states the problem (plugin scheduled tasks run once per host start until an administrator binds a schedule), the approach (a default_trigger on scheduled_task.v1 capabilities, field 14…
Full details: Title check

Explanation

The title names the main change: scheduled tasks gain a default schedule via a manifest descriptor. The changeset adds a default_trigger for scheduled_task.v1 capabilities in the protobuf schema, manifest validation, converters, docs, and the example. The title is specific and matches the primary change.

Full details: Description check

Explanation

The description states the problem (plugin scheduled tasks run once per host start until an administrator binds a schedule), the approach (a default_trigger on scheduled_task.v1 capabilities, field 14, with interval, daily, weekly and startup types), and the validation and compatibility notes. It is closely related to the changeset, so it passes the lenient relevance check.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T16:52:59.608754Z ba04b73 New commits
🔒 Security Review ✅ Completed 2026-11-18T16:54:39.313311Z ba04b73 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@silo-triage silo-triage Bot added the size/XL 500–999 added + deleted lines (all files); change volume, not priority. label Nov 5, 2026
@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Comment thread docs/scheduled-task.md Resolved
@silo-kody

silo-kody Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 3 Kody Rule(s) were not evaluated

These rules declare that they need repository context beyond this diff, and the review could not retrieve it, so they were not judged on this pull request:

  • Share optional authentication service resolution across interface types
  • Find the last complete-line boundary with bounded memory
  • Identify the actual first SDK release containing new Go APIs

Quick104 and others added 5 commits November 18, 2026 15:55
A plugin's scheduled task runs once at each host start until an
administrator binds a schedule, so plugins ask admins to call the task
bindings API by hand. Let a scheduled_task.v1 capability declare a
default_trigger (interval, daily, weekly or startup) that the host uses
until an administrator sets one.

The validator checks the known trigger types' fields and accepts types it
doesn't know, which a host replaces with its own default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…own fields

A node on an older SDK in a shared database must still read a default
schedule that a newer SDK stored with extra fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…chedule

The comments said older hosts ignore the scheduled_task descriptor. Silo
hosts built before Silo-Server/silo-server#2502 read a bare plugin binary's
manifest strictly and compare the installed manifest with the live one
including unknown fields, so they refuse to install or start a plugin that
sets it. Scope the proto comment and docs/scheduled-task.md to that, and
keep the open trigger-type note for hosts that know the descriptor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
a1f871f added four example plugin binaries built at the repository root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…artup

time_of_day is in the Silo server process's time zone. Each firing runs on
one API server and startup means once when Silo starts, which the host
side guarantees. Tasks that call outside services should add their own
jitter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Quick104
Quick104 force-pushed the feat/scheduled-task-default-trigger branch from 538e694 to c9fba73 Compare November 18, 2026 15:57

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

Minor · State the host compatibility requirement. · README.md:26

examples/hello-scheduled-task/README.md:26
Minor · Functional Correctness · Quick win

State the host compatibility requirement.

A Silo host built before silo-server#2502 refuses to install this binary because its manifest now contains scheduled_task. Add a prerequisite here or link to the compatibility notes in docs/scheduled-task.md.

Nitpick comments: 2

pkg/pluginsdk/manifest/scheduled_task_test.go: 1

35-35: Trivial · Maintainability & Code Quality · Quick win

Cover both ways to omit the default trigger.

Every fixture sets ScheduledTask and DefaultTrigger. Make ScheduledTask a table field so the test can cover both an absent descriptor and a descriptor with no default trigger. Add an interval_ms: 60000 case to protect the inclusive minimum.

pkg/pluginsdk/convert/scheduled_task_test.go: 1

16-18: Trivial · Maintainability & Code Quality · Quick win

Add a stored-record test for interval triggers.

The weekly fixture does not exercise interval_ms. ProtoJSON writes this int64 field as a JSON string. Add a case that checks that IntervalMs: 60000 produces "interval_ms": "60000". Decode an independently constructed record with that value and check that it restores 60000. This tests both sides of the storage format without relying on the writer to build the decoder fixture. (raw.githubusercontent.com)

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 11c6b453-dfb4-46c8-ad78-51400d8638de
Commits

Reviewing files that changed from the base of the PR and between 5717267 and c9fba73.

Files ignored due to path filters: 1

  • pkg/pluginproto/silo/plugin/v1/common.pb.go is excluded by !**/*.pb.go
Files selected for processing: 10

  • README.md
  • docs/scheduled-task.md
  • examples/hello-scheduled-task/README.md
  • examples/hello-scheduled-task/manifest.json
  • pkg/pluginsdk/convert/convert.go
  • pkg/pluginsdk/convert/scheduled_task_test.go
  • pkg/pluginsdk/manifest/manifest.go
  • pkg/pluginsdk/manifest/scheduled_task.go
  • pkg/pluginsdk/manifest/scheduled_task_test.go
  • proto/silo/plugin/v1/common.proto

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@silo-kody

silo-kody Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@Quick104
Quick104 merged commit fc3d204 into main Nov 18, 2026
4 checks passed
@Quick104
Quick104 deleted the feat/scheduled-task-default-trigger branch November 18, 2026 18:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update go code size/XL 500–999 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant