v0.0.2

Unofficial OpenCode plugin: weather, time, polled timers and local speech tools.

opencode plugin add @joe-broadhead/opencode-utilities

npm: @joe-broadhead/opencode-utilities@0.0.2

Added

• README sections for what to do after plugin add (opencode reload, then /utilities-status) and for updating with opencode plugin update. Uninstall now signs out of Open-Meteo first, while the plugin is installed, and names both data folders.

Changed

• The tools RPC's envelope errors use the wording shared by every plugin in this family. describe with any input but {} now says describe takes no input (before: Expected never at ["sessionID"]), and an envelope that is not an object says the envelope must be an object, such as {"sessionID":"<session>","input":<the tool's input>} (before: Expected an object).
• The status RPC (utilities.tools status) has the fields every plugin in this family now shares, with the same names and meanings: version, host { version, range, tested }, state, unguardedAgents and nextStep. Renamed: host.found → host.version, host.required → host.range, host.availability → host.tested, permissions.unguardedAgents → unguardedAgents, permissions.next → nextStep, which is now always present and equals the Next step row. New: state and speech.preseeded. The utilities_status tool and the status script method follow: permissions.unguardedAgents (a count) → unguardedAgents, next → nextStep.
• OpenCode 2.2.5 is a tested host, with 2.2.3 and 2.2.4. Another 2.2 release still runs normally, but status now calls it untested (2.2.6 (untested; supported range >=2.2.3 <2.3.0), host.tested: false) instead of tested.
• Status lists an agent without the default rules only when its own rules would run a Utilities side effect without asking. An agent whose rules already ask or deny for every one, such as an agent that ends with * * ask, is no longer listed.
• A fresh install's status reads Next step: Nothing to do. It used to send every user to the 105 MB speech download, or to the Open-Meteo key. The Speech files row still says how to install the speech files, and missing pre-seeded files still set the next step.
• Timers are per project, as the docs said. Before, each folder of a project had its own timers, so a timer set at the project root was missing in a subfolder. Timers that 0.0.1 kept per folder move into the project's store the first time a timer tool or status runs in that folder: none are lost, a duplicate is kept once, and a different timer whose name is taken is kept as <name> (2). Default synthesis files go to a per-project folder too.
• Business days skip only the holidays a whole country observes. Before, utilities_time_business_days with country: "GB" also skipped holidays of only one nation, such as Scotland's Summer Bank Holiday, for all of the UK. A new optional region parameter (England, Wales, Scotland or Northern Ireland, with country: "GB") counts that nation's holidays too. A count lists the regional holidays it did not skip in regional_holidays_not_skipped.
• Holiday lists and checks still show regional holidays, now with nationwide and regions fields on every holiday, not only the bracket in the name. utilities_time_holidays takes region too.

Fixed

• The scripting docs gave the wrong place for opencode api calls. They run in the service's default location, your home folder, not the directory you run them in, so a script's timer reads see the home folder's project. docs/scripting.md shows how to call a project through the HTTP API with ?location[directory]=, and that opencode api exits 1 when a call fails.
• The README's Speech files section overstated pre-seeding: a file missing from speech.assetsDir is taken from the cache when a verified copy is there.
• A symbolic link above the plugin's state, cache or install folder no longer breaks it. On Fedora Atomic and Silverblue (/home is a link to /var/home), with stateRoot or speech.assetsDir under macOS /tmp, or with a dotfile link to ~/.local or ~/.cache, every module failed, and time and weather wrongly reported INTEGRITY_MISMATCH. The plugin now resolves its roots once at startup and refuses links only inside its own folders. Such a link is now UNSAFE_PATH, never an integrity failure, and status reports it per module.
• A daylight-saving gap or overlap, and a date outside the holiday data, no longer reach the model as a bare BACKEND_FAILED: The program behind this tool reported an error. They are now TIME_NONEXISTENT, TIME_AMBIGUOUS (with both UTC offsets, so the model can ask which one and retry with it), TIME_OFFSET_MISMATCH, HOLIDAY_COVERAGE and TIME_OUT_OF_RANGE, each with its own next step.
• Date-times without seconds, such as 2026-03-29T02:30, work. The tools accepted them, but the time program rejected them with BACKEND_FAILED.
• The weather cache works. Each call ran weather-signal with a cache folder that was deleted afterwards, so every call re-fetched the place and the forecast (two requests against the free tier's 10,000 a day) and every result said "cache": "miss". The cache now lives in ~/.cache/opencode-utilities/weather ($XDG_CACHE_HOME), private to you: a forecast is reused for 30 minutes and a place search for 30 days. Entries older than 31 days are removed at startup.
• A script's refusal names the action that was refused. speech_transcribe with the speech files missing said utilities_speech_transcribe was refused, though the refused ask was the download, and its next step pointed at the wrong rule. It now says utilities_speech_transcribe needs utilities_speech_download, which was refused …, with Add an allow rule for utilities_speech_download … as the next step.
• An out-of-range date says which range applies, for example date: must be from 2000 to 2030, the years the offline holiday data covers, instead of date: Invalid input. Time zone, date and date-time errors name their rule too.

Verify

This version was published from this tag by GitHub Actions, through npm trusted publishing, with provenance. To check the registry signature and the provenance attestation after installing it, run npm audit signatures.

Speech files

The assets below are the speech engines and models that the plugin downloads on the first transcription or synthesis, or with /utilities-speech-install. manifest/speech-assets.json pins every file by SHA-256. Each engine also has a build provenance attestation: verify one with gh attestation verify <file> --repo joe-broadhead/opencode-utilities. macOS x64 has no speech engine.