Skip to content
Open
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
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ is `skillhook`. User docs: `README.md`, `docs/`, `llms.txt`.

| Path | What lives there |
| --- | --- |
| `src/cli.ts` → `src/commands/main.ts` | CLI entry; `HELP` there is the command reference. One file per command in `src/commands/`. |
| `src/cli.ts` → `src/commands/main.ts` | CLI entry (it first makes the built-in `fetch` use HTTP/1.1: `src/http1.ts`); `HELP` there is the command reference. One file per command in `src/commands/`. |
| `src/server.ts` | `node:http` server: webhook, health and admin routes. No framework. |
| `src/auth.ts` | Signature/token verification and the matching `signRequest` (used by `send`, MCP and tests). |
| `src/skills.ts` | SKILL.md parsing (zod), auth normalization, `loadSkills` for one directory. |
Expand Down Expand Up @@ -51,7 +51,7 @@ Runtime state lives outside the repo in `~/.skillhook` (`SKILLHOOK_HOME`):

## Hard rules

- **Runtime dependencies stay at three**: `@modelcontextprotocol/server`, `yaml`, `zod`. Everything else is `node:` built-ins. Node >= 22, ESM, TypeScript strict, imports end in `.js`.
- **Runtime dependencies stay at four**: `@modelcontextprotocol/server`, `yaml`, `zod`, and `undici` (no dependencies of its own, used only by `src/http1.ts` so that the built-in `fetch` speaks HTTP/1.1; RA-020). Everything else is `node:` built-ins. Node >= 22, ESM, TypeScript strict, imports end in `.js`.
- **Security is not optional.** The server binds `127.0.0.1` by default; TLS and public exposure are Tailscale's job. Every webhook goes through `verifyRequest`; every admin route through `requireAdmin`. Compare secrets only with `safeEqual`. A skill without `auth` gets a bearer token (`SKILLHOOK_SECRET_<NAME>`); `auth: none` must be explicit and is warned about. Secret values are never logged, never returned by an API/tool except once at generation, and never written into job files (`redactHeaders`). The agent's environment is an allow-list (`src/runners/env.ts`); `SKILLHOOK_ADMIN_TOKEN` and `SKILLHOOK_SECRET_*` are never forwarded implicitly.
- **Payloads are data.** Anything that reaches the prompt from a webhook is wrapped in `<webhook_payload>` and the guardrails say so. Never build a prompt by concatenating payload text outside those blocks.
- **Skills are Agent Skills.** Standard frontmatter (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`) plus a `skillhook:` block. `name` must equal the directory name. New fields: add to the zod schema in `src/skills.ts`, to `docs/skills.md`, to `plugins/skillhook/skills/skillhook-authoring/SKILL.md`, and cover them in `src/skills.test.ts` — in the same PR. `schedule` and `webhook` are block fields like any other (normalized by `resolveSchedule`, documented in `docs/schedules.md`). A hook in `skillhook.yaml` is the same block plus exactly one of `run` / `skill` / `prompt` (`HookSchema` in `src/projects.ts` extends `SkillhookBlockSchema`, so new block fields reach hooks automatically); hook-only fields go in `src/projects.ts`, `docs/projects.md`, `pnpm run schema` and `src/projects.test.ts`. A compiled hook is an ordinary `Skill` (with `source.type === "project"`); never special-case hooks in the server, queue or runners.
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ All notable changes to skillhook, newest first. The format follows [Keep a Chang

## Unreleased

- Every skillhook command, the server included, now makes the built-in `fetch` use HTTP/1.1 on every Node version, as Node 22 did. Node 26's `fetch` negotiates HTTP/2 with servers that offer it, and on 2026-11-10 and 2026-11-13 the daemon spun inside Node's native HTTP/2 write path until macOS killed it for memory, stopping all jobs for about 30 minutes each time (RA-020). `src/cli.ts` installs a global dispatcher from the `undici` package with `allowH2: false` before any command runs, the way Node documents configuring `fetch`; `undici` (no dependencies of its own) is the fourth runtime dependency. When `NODE_USE_ENV_PROXY` asks Node for its proxy-aware dispatcher, that one is kept.
- An automatic update no longer bricks the server when the new version rejects the current `skillhook.json`. Before restarting onto a newer version on disk, the server runs that version's `config show --json` against its home. If the new version rejects the config, the server logs `newer version installed but it rejects the current config; keeping this version running` with the error, keeps running, and checks again every minute, so fixing `skillhook.json` lets the restart go ahead. If the check cannot run (it times out, or node is missing), the server restarts as before. On 2026-11-12, 0.16.0 rejected `accounts.*.usage_login` keys that 0.15.2 had accepted. launchd then restarted the daemon 128 times, and it ran no jobs for 17 minutes.

## 0.16.0 (2026-11-10)
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ so you never touch your real `~/.skillhook`.

## Pull requests

- Keep runtime dependencies at three (`@modelcontextprotocol/server`, `yaml`, `zod`).
- Keep runtime dependencies at four (`@modelcontextprotocol/server`, `yaml`, `zod`, `undici`).
- Add or update tests next to the code (`src/**/*.test.ts`); the HTTP and CLI suites
use the fake runners in `test/fixtures/`.
- Update the docs that describe what you changed (`README.md`, `docs/`, the plugin
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@
},
"dependencies": {
"@modelcontextprotocol/server": "^2.3.1",
"undici": "^7.30.2",
"yaml": "^2.9.1",
"zod": "^4.6.6"
},
Expand Down
9 changes: 9 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions src/cli.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
#!/usr/bin/env node
import { main } from "./commands/main.js";
import { useHttp1ForFetch } from "./http1.js";

useHttp1ForFetch();

main(process.argv.slice(2)).then(
(code) => {
Expand Down
83 changes: 83 additions & 0 deletions src/http1.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
import { execFileSync } from "node:child_process";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import http2 from "node:http2";
import type { AddressInfo } from "node:net";
import { tmpdir } from "node:os";
import path from "node:path";
import tls from "node:tls";
import { Agent, getGlobalDispatcher, setGlobalDispatcher } from "undici";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { useHttp1ForFetch } from "./http1.js";

// RA-020: the built-in fetch must not negotiate HTTP/2, whatever Node's bundled undici prefers.
// A throwaway self-signed certificate made at test time (nothing is committed); no openssl, no test.
function makeCert(): { dir: string; key: string; cert: string } | undefined {
const dir = mkdtempSync(path.join(tmpdir(), "skillhook-http1-"));
try {
execFileSync(
"openssl",
["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-subj", "/CN=localhost", "-addext", "subjectAltName=IP:127.0.0.1,DNS:localhost", "-days", "1", "-keyout", path.join(dir, "key.pem"), "-out", path.join(dir, "cert.pem")],
{ stdio: "ignore", timeout: 20_000 },
);
return { dir, key: readFileSync(path.join(dir, "key.pem"), "utf8"), cert: readFileSync(path.join(dir, "cert.pem"), "utf8") };
} catch {
rmSync(dir, { recursive: true, force: true });
return undefined;
}
}

const tlsFiles = makeCert();

describe.skipIf(!tlsFiles)("useHttp1ForFetch", () => {
const { key, cert } = tlsFiles ?? { key: "", cert: "" };
let server: http2.Http2SecureServer;
let port = 0;
const previous = getGlobalDispatcher();
const sockets = new Set<tls.TLSSocket>();

beforeAll(async () => {
// Offers h2 and http/1.1 in ALPN, prefers h2, and answers with the HTTP version the request came in on.
server = http2.createSecureServer({ key, cert, allowHTTP1: true }, (req, res) => {
res.end(req.httpVersion);
});
server.on("secureConnection", (socket: tls.TLSSocket) => {
sockets.add(socket);
socket.on("close", () => sockets.delete(socket));
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
port = (server.address() as AddressInfo).port;
});

afterAll(async () => {
setGlobalDispatcher(previous);
// Kept-alive connections (h2 sessions, HTTP/1.1 keep-alive) would hold close() open.
const closed = new Promise<void>((resolve) => server.close(() => resolve()));
for (const socket of sockets) socket.destroy();
await closed;
if (tlsFiles) rmSync(tlsFiles.dir, { recursive: true, force: true });
});

it("the test server negotiates h2 with a client that offers it", async () => {
const protocol = await new Promise<string | false | null>((resolve, reject) => {
const socket = tls.connect({ host: "127.0.0.1", port, ca: cert, servername: "localhost", ALPNProtocols: ["h2", "http/1.1"] }, () => {
resolve(socket.alpnProtocol);
socket.end();
});
socket.on("error", reject);
});
expect(protocol).toBe("h2");
});

it("the built-in fetch gets HTTP/2 from it when its dispatcher allows h2 (the control)", async () => {
setGlobalDispatcher(new Agent({ connect: { ca: cert }, allowH2: true }));
const response = await fetch(`https://127.0.0.1:${port}/`);
expect(await response.text()).toBe("2.0");
});

it("makes the built-in fetch use HTTP/1.1", async () => {
useHttp1ForFetch({ connect: { ca: cert } });
const response = await fetch(`https://127.0.0.1:${port}/`);
expect(response.status).toBe(200);
expect(await response.text()).toBe("1.1");
});
});
16 changes: 16 additions & 0 deletions src/http1.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import { Agent, setGlobalDispatcher } from "undici";

/**
* Makes Node's built-in `fetch` speak HTTP/1.1 for the rest of the process, as it did on Node 22 (RA-020).
*
* Node 26's bundled undici offers `h2` in ALPN, so every HTTPS `fetch` (the cloud link, update checks, Sentry) ran
* over a native HTTP/2 session; twice a daemon spun inside `Http2Session::SendPendingData` until macOS killed it.
* Node documents a global dispatcher from the `undici` package as the way to configure the built-in `fetch`; with
* `allowH2: false` it negotiates only `http/1.1`. Called by `src/cli.ts` before any command runs, so every command
* behaves the same; the library entry (`src/index.ts`) leaves its host's dispatcher alone. When `NODE_USE_ENV_PROXY`
* asked Node for its own proxy-aware dispatcher, that one is kept. `options` exists for tests (a CA to trust).
*/
export function useHttp1ForFetch(options: Agent.Options = {}): void {
if (process.env.NODE_USE_ENV_PROXY === "1" || process.execArgv.includes("--use-env-proxy")) return;
setGlobalDispatcher(new Agent({ ...options, allowH2: false }));
}
Loading