oc-internal-schedule

OpenCode plugin that adds real scheduling tools capable of sending deferred prompts back into an existing session via POST /session/:sessionID/prompt_async.

What it does

• stores scheduled jobs in a local JSON file
• supports one-shot jobs and recurring jobs
• dispatches prompts to an existing OpenCode session
• exposes actual OpenCode tools usable by an agent

Added tools

• schedule_self_message
• list_scheduled_self_messages
• cancel_scheduled_self_message

These tools automatically use the current OpenCode sessionID.

Install into OpenCode

OpenCode can load the plugin directly from npm by package name.

Example opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aidalinfo/oc-internal-schedule"]
}

Restart OpenCode after updating the config.

Verify that OpenCode now exposes:

• plugin tools:
  • schedule_self_message
  • list_scheduled_self_messages
  • cancel_scheduled_self_message

The plugin also injects native usage guidance into the agent prompt, so the agent can often learn to use the tools even without the optional skill.

Skill (Optional)

The companion skill is optional. The plugin already teaches the agent the core usage rules through native plugin hooks.

Use the skill only if you want extra examples and more explicit teaching material.

The companion skill teaches the agent:

• when a delayed self-reminder is useful
• when a recurring reminder is better than a one-shot reminder
• when to list existing reminders before creating a new one
• how to cancel an obsolete reminder

Skill name:

• oc-internal-schedule

Skill setup details are documented in:

• skill/README.md

Test Prompts

Quick access check

Vérifie si tu as accès aux tools `list_scheduled_self_messages`, `schedule_self_message` et `cancel_scheduled_self_message`, puis utilise `list_scheduled_self_messages`.

Skill loading check

Charge le skill `oc-internal-schedule` puis explique quand tu utiliserais `schedule_self_message` plutôt qu'un simple rappel textuel.

One-shot reminder test

Charge le skill `oc-internal-schedule`, puis utilise `schedule_self_message` pour te rappeler dans 2 minutes de relire les logs du run courant et m'en faire un retour ici.

Recurring reminder test

Charge le skill `oc-internal-schedule`, puis utilise `schedule_self_message` pour te rappeler toutes les 10 minutes de vérifier l'état du scheduler et me résumer la situation.

Cancel test

Utilise `list_scheduled_self_messages` pour trouver le dernier rappel planifié dans cette session, puis annule-le avec `cancel_scheduled_self_message`.

Minimal direct prompt

Utilise le tool `schedule_self_message` pour te rappeler dans 2 minutes de relire les logs du run courant et m'en faire un retour ici.

Persistence model

• jobs are stored in ~/.local/share/opencode/internal-schedule/jobs.json
• if OpenCode stays running, timers fire at the planned time
• if OpenCode restarts, jobs are reloaded and re-armed on plugin init

Current limitation:

• if OpenCode is completely stopped at the scheduled time, the message cannot be injected until OpenCode is started again and the plugin reloads

Why this matters

OpenCode already exposes the key primitives needed for a real internal reminder tool:

• POST /session/:sessionID/message
• POST /session/:sessionID/prompt_async

This prototype proves the missing layer:

• schedule something for a session
• wake up later
• inject a prompt back into that same session

CLI

Schedule a one-shot message 5 minutes from now:

node src/cli.js schedule \
  --api-base-url http://127.0.0.1:4096 \
  --session session_123 \
  --in 5m \
  --message "Check the scheduler logs and summarize what happened."

Run due jobs once:

node src/cli.js run-due --api-base-url http://127.0.0.1:4096

Start a polling worker:

node src/cli.js daemon --api-base-url http://127.0.0.1:4096 --poll-ms 5000

List jobs:

node src/cli.js list

Cancel a job:

node src/cli.js cancel --id job_abc123

Tool behavior

schedule_self_message accepts:

• message
• in or at
• optional every
• optional agent
• optional variant
• optional system
• optional noReply

Default behavior:

• noReply defaults to false
• scheduled reminders should therefore generate a normal visible assistant reply in the session
• visible reminders now use the normal session.prompt route instead of prompt_async
• set noReply: true only if you want a silent/internal reminder without visible reply

Examples:

Planifie un self-message dans 1 minutes avec `schedule_self_message` pour vérifier mes conteneurs qui tourne stp.

Planifie un rappel toutes les 10 minutes avec `schedule_self_message` pour surveiller l'état du scheduler.

Tests

Run:

npm test

The tests cover:

• the standalone scheduler prototype against a mock HTTP server
• the real OpenCode plugin tool flow with a mocked OpenCode client

npm Publishing

This package is intended to be published as:

• @aidalinfo/oc-internal-schedule

The repository includes a GitHub Actions workflow that publishes to npm using the NPM_TOKEN secret.