Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ All notable changes to skillhook, newest first. The format follows [Keep a Chang

## Unreleased

## 0.16.0 (2026-11-10)

- A schedule can be paused without editing the file that declares it: `skillhook schedules pause <name> [--reason …] [--until 2h|<ISO>]` and `schedules resume <name>`, `POST /schedules/<name>/pause` and `/resume` (admin), and the cloud commands `schedule.pause` / `schedule.resume`. While paused nothing fires (the webhook still works); slots that pass are counted as skipped and never caught up. The pause lives in `jobs/.schedules.json`, so a repository pull or a restart keeps it, and `--until` ends it by itself. `schedules list`, `GET /health` and the cloud snapshot show `paused: {at, by, reason, until}`. This lets a repository's `skillhook.yaml` stay the source of truth for schedules while a person can still switch one off from Skillhook Cloud.
- The `service` health check now says how the server runs and whether systemd keeps it running after logout. Its details carry `run_mode` (`service`, `foreground` or `unknown`) and, on systemd, `linger` (`yes`, `no` or `unknown`, read-only from `loginctl`). A systemd service with lingering off is a `warn` with the `loginctl enable-linger` fix. Both reach Skillhook Cloud in the health report, so a machine that goes offline at logout or when its terminal closes can be told apart from one that was stopped on purpose. `service install` on Linux warns when lingering is off, and skips the tip when it is already on.
- A full disk no longer restarts the server. Recording a running job's pid or session id, and writing its stdout/stderr files, happened in child-process handlers outside any `try`, so `ENOSPC` reached the uncaught-exception handler: on 2026-11-11 one machine restarted 18 times in about two hours and every restart interrupted the jobs it was running. Those failures are now logged (`could not record job state`, `could not write job output`) and the job runs on.
- The published plugin mirror (`MeterApp/skillhook-plugins`, what Anthropic's plugin directory installs) no longer carries local MCP servers, a launcher script or a lockfile: the directory refuses those from organizations that are not Verified. It now has the skills and the hosted Skillhook Cloud server, which the host signs in to with the browser. This repository's own marketplace (`/plugin marketplace add MeterApp/skillhook`) keeps both local servers, and `skillhook mcp --print-config` adds the local one to any host.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -385,7 +385,7 @@ Agents reading this repository should start with [`AGENTS.md`](AGENTS.md) (layou
| `skillhook config show\|get <key>\|set <key> <value>\|unset <key>\|reload\|path` | Read and edit `skillhook.json`; `set`/`unset` tell the running server, which applies every key but `host` and `port` live. |
| `skillhook link [dir] [--no-secret]` / `skillhook unlink <dir>` | Serve the hooks a repository declares in its `skillhook.yaml` (default `.`); stop serving them. |
| `skillhook projects [list]` / `skillhook projects init [dir] [--force]` | List linked repositories and their hooks; write a starter `skillhook.yaml` and link it. |
| `skillhook schedules [list]` · `schedules next <name> [--count N]` · `schedules run <name> [--wait S]` | Every skill or hook with a `schedule:`, its next and last runs; preview occurrences; fire one now. |
| `skillhook schedules [list]` · `schedules next <name> [--count N]` · `schedules run <name> [--wait S]` · `schedules pause <name> [--reason T] [--until 2h]` · `schedules resume <name>` | Every skill or hook with a `schedule:`, its next and last runs; preview occurrences; fire one now; pause one without editing its file, and resume it. |
| `skillhook update [--install]` | Check npm for a newer skillhook; `--install` upgrades with the package manager that installed it and restarts the background service when it is idle. |

Global options: `--dir <path>` (default `$SKILLHOOK_HOME` or `~/.skillhook`), `--json` (machine-readable output for every command), `--help` (on any command or subcommand, or `skillhook help <command>`: prints its usage and runs nothing), `--version`. Exit codes: 0 success, 1 failure, 2 usage error. Environment: `SKILLHOOK_HOME`, `SKILLHOOK_NO_UPDATE_CHECK=1` (or `CI`) to turn off the hourly update check and automatic updates, `SKILLHOOK_NPM_REGISTRY` for a mirror, `SKILLHOOK_DEBUG=1` for stack traces. HTTP API: [docs/api.md](docs/api.md). Service, logs, jobs, config and troubleshooting: [docs/operations.md](docs/operations.md).
Expand Down
1 change: 1 addition & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Related: [security.md](security.md) (authentication), [skills.md](skills.md) (fi
| `GET` | `/stats` | admin | Numbers over jobs and deliveries: by status, outcome, runner, failure kind; durations, cost, tokens; per skill (`?since=24h`, `?until=`, `?skill=`). |
| `GET`, `PATCH` | `/config` | admin | The live `skillhook.json` (defaults applied) with what applies live and what needs a restart; change keys in one validated write. |
| `POST` | `/config/reload` | admin | Re-read `skillhook.json` (after editing it by hand). |
| `POST` | `/schedules/<name>/pause`, `/schedules/<name>/resume` | admin | Pause a schedule (body `{reason?, until?, by?}`) or resume it; answers `{ok, schedule}`. `404` for an unknown skill, `409` for one without a schedule, `400` for an `until` that is not a future instant ([schedules.md](schedules.md#pausing-a-schedule)). |
| `POST` | `/control/restart` | admin | Pause dispatch, exit only if active jobs finish within the bound; otherwise resume dispatch. `409` when not run as the service. |
| `GET` | `/service` | admin | The launchd / systemd service status. |
| `GET` | `/logs` | admin | The last lines of the service log (`?lines=200`). |
Expand Down
1 change: 1 addition & 0 deletions docs/cloud-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ Errors are `SyncError` `{ok: false, error, message?, retry_after_ms?, min_protoc

## Command results worth knowing

- `schedule.pause`, `schedule.resume`: `{schedule}`, the schedule's status as `schedules.list` gives it, with `paused: {at, by?, reason?, until?}` or `null`. Machines before 0.17.0 do not know these types, and a machine refuses a whole sync response that carries a command type it does not know, so the cloud must send them only to machines that report 0.17.0 or later.
- `skill.run`, `skill.test`, `delivery.replay`, `job.replay`, `schedule.run`: `{accepted: true, job_id, …}` (a replay whose filters do not match: `{accepted: false, skipped: true, reason}`); the job itself is followed through its events.
- `job.answer`: `{job_id, delivered: live|resumed|recorded, answer, resume_job_id}`.
- `config.patch`: `{applied, restart_required_keys, pending_restart}`.
Expand Down
3 changes: 2 additions & 1 deletion docs/cloud.md
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ A skill can have a hosted webhook URL on the cloud (the dashboard creates it) in

Read commands (both modes): `ping`, `health.get`, `snapshot.get`, `runners.get`, `accounts.get` (`{account?, refresh?, usage?}`, [what it answers](#accounts)), `skills.list`, `skill.get`, `delivery.list`, `delivery.get`, `job.list`, `job.get`, `job.artifact`, `job.watch`, `job.unwatch`, `job.progress.get`, `stats.get`, `config.get`, `secret.list` (names only), `service.status`, `logs.tail`, `schedules.list`, `update.check`, `expose.status`.

Control commands (`mode: control` or an allow entry): `skill.put`, `skill.delete`, `skill.run`, `skill.test`, `delivery.replay`, `job.cancel`, `job.replay`, `job.answer`, `config.patch`, `secret.generate`, `service.restart`, `schedule.run`, `update.install`.
Control commands (`mode: control` or an allow entry): `skill.put`, `skill.delete`, `skill.run`, `skill.test`, `delivery.replay`, `job.cancel`, `job.replay`, `job.answer`, `config.patch`, `secret.generate`, `service.restart`, `schedule.run`, `schedule.pause`, `schedule.resume`, `update.install`.

Results are scrubbed like events. Each command runs once: its id is remembered in `jobs/.cloud/commands.json`, and a command the cloud sends again is answered from the kept result.

Expand All @@ -283,6 +283,7 @@ What each control command does, and the rules it adds on top of the policy:
| `config.patch` | Changes `skillhook.json` like `PATCH /config`, except for `host`, `port`, `trust_proxy`, `runners`, `env_passthrough`, `projects`, `project_refresh` and `cloud`, which the cloud may never change. |
| `service.restart` | Restarts a server run by launchd / systemd once the cloud has the answer (`when: idle` pauses dispatch and lets running jobs finish up to `wait_seconds`, then resumes dispatch if jobs remain; `now` terminates them without waiting. Through version 0.10.4, even `idle` terminates jobs when the wait expires). |
| `schedule.run` | Fires a scheduled skill now. |
| `schedule.pause`, `schedule.resume` | Pauses a skill's or hook's `schedule:` (`{name, reason?, until?}`) or resumes it (`{name}`), like `skillhook schedules pause` / `resume`: nothing fires while paused, the webhook keeps working, missed slots are not caught up, and the pause survives repository pulls and restarts ([schedules.md](schedules.md#pausing-a-schedule)). `by` is the requester's name. The next sync carries a snapshot with the schedule's `paused`. |
| `update.install` | Installs a newer skillhook with the package manager that installed it; the server keeps running the old version until `service.restart`. |
| `secret.generate` | Generates a skill's secret (or any `ENV_NAME`) and returns it only sealed to the requester's key (`recipient_key`, required); the value never travels or rests in the clear. The machine's own credentials (`SKILLHOOK_CLOUD_*`, `SKILLHOOK_ADMIN_TOKEN`) are refused, by whatever name they are asked for (`admin`, a skill's, the variable's). |
| `skill.put` | Writes `skills/<name>/SKILL.md` after validating it. Never for a name that comes from a linked repository; `auth: none` needs `allow_unauthenticated`. No secret is created: `secret.generate` does that, sealed. |
Expand Down
15 changes: 14 additions & 1 deletion docs/schedules.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,20 @@ skillhook schedules run weekday-digest --wait 60 # fire it now with a schedul
skillhook run weekday-digest --payload '{"scheduled_for":"2026-09-24T13:05:00Z"}' --dry-run # the prompt and command a scheduled run would get
```

`skillhook skills list` shows `(schedule <cron>)` in the URL column for schedule-only hooks, `skillhook skills show <name>` prints the schedule and its next run, `GET /skills` carries `schedule: {cron, timezone, catch_up, overlap, next_run_at}` and `webhook`, and `GET /health` (admin) lists every schedule with `next_due`, `last_slot`, `last_fired_at`, `last_job`, `last_status` and `skipped`. The MCP tool is `list_schedules`.
## Pausing a schedule

The schedule is declared in the skill or the repository's `skillhook.yaml`, which stays its source of truth. To stop it firing for a while without a commit (it misbehaves, a migration runs, a service it calls is down), pause it on the machine:

```bash
skillhook schedules pause availability-sweep --reason "duplicate emails" --until 2h # or --until 2026-11-12T09:00:00Z; without --until, until resumed
skillhook schedules resume availability-sweep
```

A paused schedule fires nothing; its webhook, if it has one, keeps working, and `skillhook run` / `schedules run` still run it by hand. Slots that pass while it is paused are counted in `skipped` but are never caught up, whatever `catch_up` says: on resume (or when `until` passes) it fires from its next slot. The pause is kept in `jobs/.schedules.json`, not in the skill's file, so a repository pull, a change to the hook and a restart all leave it in place; removing the pause is always an explicit resume or the end of `until`. With a server running the command goes through it (`POST /schedules/<name>/pause` and `/resume`, admin); without one it writes the state file, and the server honours it when it starts.

Skillhook Cloud pauses and resumes the same way, with the `schedule.pause` / `schedule.resume` commands ([cloud.md](cloud.md#commands-the-cloud-may-send)); the pause records who asked.

`skillhook skills list` shows `(schedule <cron>)` in the URL column for schedule-only hooks, `skillhook skills show <name>` prints the schedule and its next run, `GET /skills` carries `schedule: {cron, timezone, catch_up, overlap, next_run_at}` and `webhook`, and `GET /health` (admin) lists every schedule with `next_due`, `last_slot`, `last_fired_at`, `last_job`, `last_status`, `skipped` and `paused` (`{at, by?, reason?, until?}` or `null`; `next_due` is `null` while paused until resumed). The MCP tool is `list_schedules`.

`skillhook doctor` adds a `schedules` line (every schedule with its next run) and, on macOS, a `sleep` line that warns when `pmset` reports a sleep timer.

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@meterapp/skillhook",
"version": "0.15.2",
"version": "0.16.0",
"mcpName": "dev.skillhook/skillhook",
"description": "Make your Agent Skills reactive. A permanent, secure webhook endpoint on your own machine that runs SKILL.md files with Claude Code or Codex the moment something happens, plus version-controlled schedules for the work that has no trigger. Webhook in, agent out.",
"license": "MIT",
Expand Down
2 changes: 1 addition & 1 deletion plugins/skillhook/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "skillhook",
"displayName": "skillhook",
"version": "0.15.2",
"version": "0.16.0",
"description": "Turn this machine into a permanent, secure webhook endpoint that runs Agent Skills with Claude Code or Codex, and run your whole Skillhook Cloud organisation from the agent. Three skills teach the agent to install and expose skillhook, to write good webhook skills and to operate the fleet; two MCP servers manage this machine (skills, secrets, jobs, exposure) and, with an organisation API key, every machine as the Skillhook Cloud dashboard does (what needs a person, failures, stats, answers, replays, runs, hosted URLs).",
"author": {
"name": "Meter",
Expand Down
2 changes: 1 addition & 1 deletion plugins/skillhook/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "skillhook",
"version": "0.15.2",
"version": "0.16.0",
"description": "Turn this machine into a permanent, secure webhook endpoint that runs Agent Skills with Claude Code or Codex, and run your whole Skillhook Cloud organisation from the agent. Three skills teach the agent to install and expose skillhook, to write good webhook skills and to operate the fleet; two MCP servers manage this machine (skills, secrets, jobs, exposure) and, with an organisation API key, every machine as the Skillhook Cloud dashboard does (what needs a person, failures, stats, answers, replays, runs, hosted URLs).",
"author": {
"name": "Meter",
Expand Down
2 changes: 1 addition & 1 deletion plugins/skillhook/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "skillhook",
"version": "0.15.2",
"version": "0.16.0",
"description": "Turn this machine into a permanent, secure webhook endpoint that runs Agent Skills with Claude Code or Codex, and run your whole Skillhook Cloud organisation from the agent. Three skills teach the agent to install and expose skillhook, to write good webhook skills and to operate the fleet; two MCP servers manage this machine (skills, secrets, jobs, exposure) and, with an organisation API key, every machine as the Skillhook Cloud dashboard does (what needs a person, failures, stats, answers, replays, runs, hosted URLs).",
"author": {
"name": "Meter",
Expand Down
4 changes: 2 additions & 2 deletions plugins/skillhook/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
"mcpServers": {
"skillhook": {
"command": "npx",
"args": ["-y", "@meterapp/skillhook@0.15.2", "mcp"]
"args": ["-y", "@meterapp/skillhook@0.16.0", "mcp"]
},
"skillhook-cloud": {
"command": "npx",
"args": ["-y", "@meterapp/skillhook@0.15.2", "mcp", "--cloud"]
"args": ["-y", "@meterapp/skillhook@0.16.0", "mcp", "--cloud"]
}
}
}
2 changes: 1 addition & 1 deletion plugins/skillhook/skills/skillhook-setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ skillhook secret set GITHUB_WEBHOOK_SECRET # the file names secrets; values st

Hooks are live without a restart, `git pull` deploys changes, and `skillhook unlink <dir>` stops serving them. Names in `~/.skillhook/skills` win over repositories; a duplicate is reported by `skillhook skills list` and `doctor`. MCP: `link_project` (`init: true` to scaffold), `list_projects`, `unlink_project`. Writing the file itself is covered by skillhook-authoring.

Hooks with a `schedule:` (cron + time zone) fire from the running server without a webhook; `skillhook schedules list` shows the next and last run of each, `skillhook schedules run <name>` fires one now. They need the server running and the machine awake (`doctor` checks both). A server older than the version that added schedules rejects a `skillhook.yaml` that uses them, so `skillhook update --install` every linked machine before merging one.
Hooks with a `schedule:` (cron + time zone) fire from the running server without a webhook; `skillhook schedules list` shows the next and last run of each, `skillhook schedules run <name>` fires one now, `skillhook schedules pause <name> [--until 2h]` / `resume <name>` stop and restart one without touching the repository (Skillhook Cloud can do the same). They need the server running and the machine awake (`doctor` checks both). A server older than the version that added schedules rejects a `skillhook.yaml` that uses them, so `skillhook update --install` every linked machine before merging one.

## 10. Pair with Skillhook Cloud (optional)

Expand Down
15 changes: 14 additions & 1 deletion src/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -516,6 +516,19 @@ describe("cli", () => {
const checks = doctor.json().checks as { name: string; status: string; detail: string }[];
expect(checks.find((c) => c.name === "skill tick")).toMatchObject({ status: "ok", detail: expect.stringContaining("schedule only") });
expect(checks.find((c) => c.name === "schedules")).toMatchObject({ status: "ok", detail: expect.stringContaining("tick (*/5 * * * *") });
const pause = io();
expect(await main(["schedules", "pause", "tick", ...dir, "--reason", "too noisy", "--until", "2h", "--json"], pause.cli)).toBe(0);
expect(pause.json()).toMatchObject({ via: "local", schedule: { skill: "tick", paused: { reason: "too noisy", by: "cli", until: expect.stringMatching(/Z$/) } } });
const pausedList = io();
expect(await main(["schedules", ...dir], pausedList.cli)).toBe(0);
expect(pausedList.out()).toContain("(paused until");
const resume = io();
expect(await main(["schedules", "resume", "tick", ...dir, "--json"], resume.cli)).toBe(0);
expect(resume.json()).toMatchObject({ via: "local", schedule: { paused: null } });
const pauseNone = io();
expect(await main(["schedules", "pause", "hello", ...dir, "--json"], pauseNone.cli)).toBe(1);
const badUntil = io();
expect(await main(["schedules", "pause", "tick", ...dir, "--until", "soonish"], badUntil.cli)).toBe(2);
const none = io();
expect(await main(["schedules", "next", "hello", ...dir, "--json"], none.cli)).toBe(1);
const usage = io();
Expand Down Expand Up @@ -1374,7 +1387,7 @@ describe("cli", () => {
link: [[], [unlinked]],
unlink: [[linked]],
projects: [[], ["list"], ["init", path.join(home.home, "fresh")], ["add", unlinked], ["remove", linked]],
schedules: [[], ["list"], ["next", "tick"], ["run", "tick"]],
schedules: [[], ["list"], ["next", "tick"], ["run", "tick"], ["pause", "tick"], ["resume", "tick"]],
};
for (const name of Object.keys(lines)) expect(COMMANDS, name).toHaveProperty(name);

Expand Down
Loading
Loading