Report issues and read the fleet from the CLI (0.6.0)

[JOsacky]

Two things a person on a machine could not do from the terminal: tell the Skillhook team about a problem, and see the rest of the fleet. Released as 0.6.0.

skillhook cloud report: problem reports from a paired machine

skillhook cloud report "GitHub deliveries fail since the update" --body-file notes.txt --job 20260929T101500Z-a1b2c3 --email ada@example.com
skillhook cloud report "Where do hosted URLs come from?" --kind question --no-diagnostics
skillhook cloud report "Replays hang" --body - --dry-run < notes.txt    # the exact JSON, nothing sent

• One request, POST {cloud.url}/api/agent/issues with the machine token, only when a person runs it. It prints Reported as #N: <url> and whether a confirmation email went out; --json prints the cloud's answer.
• It carries the person's title and body (--body TEXT, --body -, --body-file), --kind, --severity, --email, and references (--job, --delivery, --skill). Unless --no-diagnostics, it adds what the machine already knows: skillhook, Node, OS and architecture, cloud.mode, the link's state, {runner, ready} per runner, and the health summary with the failing and warning checks. These come from the running server's cached answers, or from a quick local check (no network probes) when no server runs. A server answer of another shape falls back to the basics rather than failing the report.
• Every .env value is scrubbed from the title, body, references and diagnostics before anything leaves, as for the link. A contact address that is itself a .env value is refused. Payloads, logs, prompts and job output never go. docs/cloud.md lists exactly what is sent.
• Each report carries a report_id (a UUID), the same on every attempt. Network errors, timeouts and 5xx are retried (three attempts); a 429 is retried only after a retry_after_ms of at most 15 s; any other 4xx is never retried. The cloud files a retried report once. The client reads the answer leniently, so a field a newer cloud adds cannot turn a filed report into a failure and a second report.
• Needs a paired machine (cloud.enabled and SKILLHOOK_CLOUD_TOKEN); otherwise it points to skillhook cloud connect or the dashboard / hosted MCP. Refused under SKILLHOOK_NO_CLOUD=1 and to an http URL. A refused token, a disabled machine, a rate limit and a cloud without the route (an HTML 404) each get a plain message.
• The operation is shared (src/cloud/report.ts). The MCP tool cloud_report_issue sends the same report, with dry_run to show the person first.
• --body stays a switch for deliveries show <id> --body and takes its text only after cloud report. skillhook cloud <subcommand> --help now prints the usage instead of running the subcommand (a report must not go out on --help).

Reading the fleet with an organisation API key

pbpaste | skillhook cloud login --key -    # checked with GET /api/v1/me, kept in .env, never printed
skillhook cloud machines
skillhook cloud jobs --waiting --machine mac-mini
skillhook cloud job 20260929T101500Z-a1b2c3
skillhook cloud logout

• login --key shc_…|- stores SKILLHOOK_CLOUD_API_KEY in .env (mode 600). The environment variable works too (CI) and wins. logout removes the key from .env.
• machines (name, status, mode, version, last seen), jobs [--machine M] [--skill S] [--status ST] [--outcome O] [--waiting] [--limit N] [--before C] and job <id> (status, outcome, the pending question, the result excerpt) read /api/v1. Tables by default; --json prints the API's JSON. Answers are parsed with loose schemas, since the cloud may add fields.
• The machine token is never used for these reads, so a paired machine cannot read the rest of its organisation.
• A key must look like one (shc_ then letters, digits, -, _), so a pasted second line or the machine token is refused before anything is sent.
• A key never goes to the built-in placeholder URL: until pairing, cloud.url or SKILLHOOK_CLOUD_URL names a cloud, the reads refuse. Requests are HTTPS only and are refused under SKILLHOOK_NO_CLOUD=1.
• src/cloud/http.ts now reads RFC 9457 problems (code, detail, request_id) as well as the agent API's error / message. A 401 says to run skillhook cloud login; a 403 names the missing fleet:read scope. A token that is not one line of printable characters is refused before it becomes a header (the runtime quotes a refused header in its error), and a token never appears in a transport error message.

The protocol contract (additive, PROTOCOL_VERSION stays 1)

export const ISSUE_KINDS = ["bug", "question", "feature", "other"] as const;
export const ISSUE_SEVERITIES = ["low", "normal", "high", "urgent"] as const;
// LIMITS.max_issue_report_bytes: 64 * 1024 (the request body)

export const IssueDiagnosticsSchema = z.object({
  skillhook_version: z.string().max(64).optional(),
  node_version: z.string().max(64).optional(),
  os: z.string().max(64).optional(),
  arch: z.string().max(32).optional(),
  mode: z.enum(MACHINE_MODES).optional(),
  link: z.object({ state: z.enum(LINK_STATES), reason: z.enum(LINK_REASONS).optional(), last_error: z.string().max(500).optional() }).loose().optional(),
  runners: z.array(z.object({ runner, ready: z.boolean() }).loose()).max(3).optional(),
  health: z.object({ ok: z.boolean(), summary, failing: z.array(z.object({ id: z.string().max(200), status: z.enum(CHECK_STATUSES), message: z.string().max(500).optional() }).loose()).max(50).optional() }).loose().optional(),
}).loose();

export const IssueReportRequestSchema = z.object({
  title: z.string().min(1).max(200),
  body: z.string().max(20_000).optional(),
  kind: z.enum(ISSUE_KINDS).optional(),           // the cloud defaults to "bug"
  severity: z.enum(ISSUE_SEVERITIES).optional(),  // the cloud defaults to "normal"
  contact_email: z.string().email().max(320).optional(),
  job_id: id.optional(),                          // the machine's own job id
  delivery_id: id.optional(),
  skill: name.optional(),
  diagnostics: IssueDiagnosticsSchema.optional(),
  /** A client-generated idempotency key; a retry with the same report_id returns the original report instead of filing a second one. */
  report_id: z.string().min(8).max(100).regex(/^[A-Za-z0-9_-]+$/).optional(),
}).strict();

export const IssueReportResponseSchema = z.object({ ok: z.literal(true), issue_id: id, number: z.number().int().min(1), url: z.string().url().max(2048), acknowledged: z.boolean() }).strict();

POST /api/agent/issues, Authorization: Bearer <SKILLHOOK_CLOUD_TOKEN>, JSON body ≤ 64 KiB. A 200 answer is an IssueReportResponse, the same for a new report and for a replay of the same report_id; acknowledged says whether a confirmation email went out. Errors use the agent API's shape {ok: false, error, message, retry_after_ms?}: 401 invalid_token, 403 machine_disabled, 400 invalid_request, 413 payload_too_large, 429 rate_limited, 500 server_error. Documented in docs/cloud-protocol.md#issue-reports.

Rules and docs

• AGENTS.md's "Outbound requests are opt-in and enumerated" rule now lists the person-invoked cloud commands: one request each, only when run, only to the machine's cloud URL over HTTPS. cloud report and the API-key commands refuse under SKILLHOOK_NO_CLOUD=1.
• Updated: docs/cloud.md (what cloud report sends, what the API-key commands read), docs/cloud-protocol.md, docs/mcp.md, docs/security.md, docs/operations.md, the README command table, llms.txt, the setup skill and CHANGELOG.md.
• CodeQL: no new regexes with ambiguous repetition on untrusted text, flag lookups use a Map, and nothing writes user-supplied keys.

Landing this

Merging bumps package.json to 0.6.0, so the Release workflow tags v0.6.0 and Publish ships @meterapp/skillhook@0.6.0. The cloud (MeterApp/skillhook-cloud, which vendors 0.5.0 today) needs 0.6.0 for IssueReportRequestSchema. Until its /api/agent/issues route is deployed, cloud report says the cloud does not take reports yet.

Tests

• npm run check: 43 files, 279 tests, build, schemas and release metadata (0.6.0).
• New tests cover:
  • the schemas (valid, invalid, limits, report_id);
  • the report with and without diagnostics, both from a running server (src/test-support/fake-server.ts) and from a local check with the fake CLIs;
  • scrubbing of .env values in the title, body, references and diagnostics;
  • the not-paired, kill-switch, https and size refusals;
  • every error the cloud can answer, and which of them are retried;
  • the retry and idempotency path, including an answer lost after the report was filed;
  • the HTTP client's problem parsing and credential redaction;
  • login keeping the key without printing it (flag and stdin), a two-line key, and no key sent without a cloud URL;
  • 401 and 403 messages, table output and --json, the machine token never reaching /api/v1, and --help;
  • the MCP tool, including dry_run.
• The fake cloud serves /api/agent/issues (once per report_id, with scripted failures) and the /api/v1 reads for one key.
• An independent review pass over the diff found issues (the placeholder URL, credentials in fetch errors, --help, --diagnostics false, odd server answers, unscrubbed references, strict answer parsing); all are fixed here, with tests.

🤖 Generated with Claude Code