@impulselab/hepha 0.2.94 → 0.2.96

package/README.md

@@ -45,3 +45,48 @@ CLI at another Hephaistos deployment.
 - `1`: failed, killed, or abstained
 - `2`: invalid CLI usage
 - `3`: waiting for a human question or approval
+
+## Agent skill
+
+The package ships `skills/cli/SKILL.md`, an [Agent
+Skill](https://agentskills.io) that teaches a coding agent what the platform
+does and how to drive it — task types, the question cycle, the four guardrails,
+then the commands, the exit codes and the mistakes that look right. Install the
+package and the knowledge travels with it; `npm update` updates it.
+
+```bash
+npx @tanstack/intent@latest install       # writes discovery guidance once
+npx @tanstack/intent@latest list --global # the CLI is usually installed globally
+npx @tanstack/intent@latest load @impulselab/hepha#cli
+```
+
+Nothing runs on install: the skill is a file in the tarball and the tooling
+reads it out of `node_modules`, never executing package code. Discovery is
+opt-in per source, in the consuming project's `package.json`:
+
+```json
+{
+  "intent": {
+    "skills": ["@impulselab/hepha"],
+    "exclude": ["@impulselab/hepha#experimental-*"]
+  }
+}
+```
+
+`intent.skills` is the package-level allowlist (`"*"` allows everything, `[]`
+nothing), `intent.exclude` the finer control down to `package#skill`. That list
+is the boundary — `intent hooks install` only nudges an editor to surface skill
+loading, and must never be what decides a skill is safe to load.
+
+### Maintaining it
+
+`sources:` in the skill's frontmatter names the files it is distilled from.
+
+```bash
+pnpm --filter @impulselab/hepha exec intent validate skills   # blocking in CI
+pnpm --filter @impulselab/hepha run skills:stale              # advisory
+```
+
+`.github/workflows/skills.yml` validates the skill on every PR that touches it,
+and reports — without failing the build — when a PR edits a declared source
+without touching the skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impulselab/hepha",
-  "version": "0.2.94",
+  "version": "0.2.96",
   "description": "Command-line interface for the Hepha platform.",
   "type": "module",
   "repository": {
@@ -12,6 +12,16 @@
   "bugs": {
     "url": "https://github.com/impulse-studio/hephaistos/issues"
   },
+  "keywords": [
+    "hephaistos",
+    "agent-skills",
+    "tanstack-intent"
+  ],
+  "intent": {
+    "version": 1,
+    "repo": "impulse-studio/hephaistos",
+    "docs": "https://hephaistos.impulselab.ai/api/v1/docs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -20,13 +30,16 @@
     "hepha": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsup",
     "dev": "tsx src/index.ts",
     "types:check": "pnpm --filter @repo/ui run build && tsc --noEmit",
     "test": "find src -name '*.test.ts' -type f -exec tsx --test {} +",
+    "skills:validate": "intent validate skills",
+    "skills:stale": "intent stale .",
     "prepublishOnly": "npm run types:check",
     "prepack": "tsup"
   },
@@ -38,6 +51,7 @@
     "@repo/database": "workspace:*",
     "@repo/server": "workspace:*",
     "@repo/typescript-config": "workspace:*",
+    "@tanstack/intent": "0.3.6",
     "@types/node": "^22.15.3",
     "tsup": "^8.4.0",
     "tsx": "^4.19.4",

package/skills/cli/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: cli
+description: >
+  Drive the Hephaistos code factory from a terminal or a script with the
+  `hepha` CLI: create a session from a prompt, follow its transcript, answer
+  its question rounds, read the delivery, and escalate guardrail approvals to
+  a human. Load when the task mentions hepha, Hephaistos, HEPHA_API_KEY,
+  `hepha run`, exit code 3, waiting_human, awaiting_approval, question
+  batches, or the `/api/v1` public API.
+metadata:
+  type: core
+  library: "@impulselab/hepha"
+  library_version: "0.2"
+sources:
+  - "impulse-studio/hephaistos:apps/cli/README.md"
+  - "impulse-studio/hephaistos:apps/cli/src/commands/*.ts"
+  - "impulse-studio/hephaistos:apps/cli/src/lib/follow.ts"
+  - "impulse-studio/hephaistos:apps/cli/src/lib/session-outcome.ts"
+  - "impulse-studio/hephaistos:packages/database/constants.ts"
+  - "impulse-studio/hephaistos:packages/server/src/routers/v1/*/router.ts"
+  - "impulse-studio/hephaistos:packages/server/src/routers/v1/schemas.ts"
+---
+
+# Hephaistos from the command line
+
+## What the platform does
+
+Hephaistos is a code factory: a demand goes in, a **session** carries it to a
+delivered result. One session is one accountable run — it owns an isolated
+cloud sandbox, a transcript, and a lifecycle you can drive from this CLI.
+
+| Task type     | What the session produces                                   |
+| ------------- | ----------------------------------------------------------- |
+| `implement`   | A change on an existing repo, delivered as a pull request   |
+| `new-project` | A new repo scaffolded, provisioned, planned and implemented |
+| `question`    | An answer — no git setup, repos cloned read-only to explore |
+| `draft`       | Written output (email, spec, recap) — no code delivery      |
+
+Three platform behaviours decide how a caller must drive a session:
+
+- **The question cycle is infinite.** An agent that is not confident asks
+  instead of guessing. The session moves to `waiting_human` and stays there
+  forever until a round is answered — it costs nothing and never times out.
+  Answering is a normal scope, so a script or an agent can do it.
+- **Four guardrails are human-only**: merge a pull request, touch production,
+  reply to an external client, push to a main branch. The session moves to
+  `awaiting_approval` and an API key can read the request but never decide it.
+- **Delivery is proven, not claimed.** A finished code session carries a PR
+  URL, a verification report (tests + recorded proof) and its CI status —
+  read them to judge the result.
+
+Sessions run in parallel on the same repo without conflict: isolation is by
+branch, and collisions are resolved at PR time.
+
+## Setup
+
+```bash
+npm install --global @impulselab/hepha
+
+# Agents: a key minted by a human with `hepha keys create`.
+export HEPHA_API_KEY=hepha_xxxxxxxxxxxxxxxxxxxxxxxx
+hepha whoami --json
+```
+
+`whoami --json` reports the scopes actually in play — read it first and fail
+early instead of halfway through a task.
+
+| Variable           | Effect                                                              |
+| ------------------ | ------------------------------------------------------------------- |
+| `HEPHA_API_KEY`    | Act as an agent. **Takes precedence** over a stored `hepha login`.  |
+| `HEPHA_TOKEN`      | A device-flow token, instead of `~/.hepha/config.json`.             |
+| `HEPHA_URL`        | Platform base URL (a dev box points it at `http://localhost:3000`). |
+| `HEPHA_TIMEOUT_MS` | Per-request timeout, default `30000`.                               |
+
+Humans sign in with `hepha login` (device authorization, approved in a
+browser). It is the one interactive command and the one that does not honour
+`--json`. An agent should never run it.
+
+Scopes are `resource:action`: `sessions:read`, `sessions:write`,
+`questions:read`, `questions:answer`, `approvals:read`, `catalog:read`,
+`pull_requests:read`. A key created without `--scope` is read-only across
+every resource, and scopes can never be widened — only replaced by a new key.
+
+## Core patterns
+
+### Start a session and follow it to its outcome
+
+```bash
+hepha repos --json                      # repoFullName must exist in the catalog
+hepha run "Add rate limiting to the public API" \
+  --repo impulse-studio/hephaistos \
+  --task-type implement \
+  --follow
+```
+
+`run --follow` creates the session, streams the transcript, and returns the
+moment the run finishes or needs a person. The exit code carries the outcome
+so nothing has to be parsed:
+
+| Code | Meaning                                                  |
+| ---- | -------------------------------------------------------- |
+| `0`  | Session completed                                        |
+| `1`  | Failed, killed or abstained (message on stderr)          |
+| `2`  | Usage error (unknown flag, missing argument, bad value)  |
+| `3`  | **Blocked on a human** — a question round or a guardrail |
+
+### Branch a script on the outcome
+
+```bash
+result=$(hepha run "$PROMPT" --repo "$REPO" --follow --json)
+status=$?
+session=$(jq -r '.id // .result.id // empty' <<<"$result")
+
+case "$status" in
+  0) hepha sessions pr "$session" --json ;;
+  3) hepha questions list --session "$session" --json ;;
+  *) exit "$status" ;;
+esac
+```
+
+Under `--json` the session is the document on success and rides in `.result`
+on a non-zero exit, so `.id // .result.id` names the session either way — the
+id is never printed anywhere else.
+
+Exit `3` is not a failure: it is the platform asking for input. Answer the
+round (or escalate the guardrail), then keep following.
+
+### Answer a question round
+
+```bash
+hepha questions list --json                    # batches waiting on you
+hepha questions show <batchId>                 # ids, options, recommendation
+hepha questions answer <batchId> \
+  --option q_01=2 \
+  --text q_02="Use Postgres, not SQLite"
+```
+
+`--option <questionId>=<optionId>[,<optionId>]` selects; `--text
+<questionId>=…` adds free text; both may target the same question. For an
+agent, one flag carries the whole round:
+
+```bash
+hepha questions answer <batchId> \
+  --answers '[{"questionId":"q_01","selectedOptionIds":["2"]},{"questionId":"q_02","freeText":"Use Postgres"}]'
+```
+
+Then resume following: `hepha sessions logs <id> --follow`.
+
+### Poll a transcript incrementally
+
+```bash
+hepha sessions logs <id> --after 128 --limit 200 --json
+```
+
+`--after <sequence>` returns only what came after that event. The page carries
+`nextCursor` — pass it back as `--after` — and `hasMore`, which is `false`
+when you are caught up. `--follow` blocks until the session finishes or parks.
+
+### Collect the delivery
+
+```bash
+hepha sessions get <id> --json        # status, prUrl, playbook
+hepha sessions verify <id> --json     # test report and recorded proof
+hepha sessions pr <id> --json         # CI status of the delivered PR
+hepha sessions checks <id>            # re-run the repo's checks
+```
+
+### Hand a guardrail to a human
+
+```bash
+hepha approvals list --json           # readable with approvals:read
+hepha approvals show <id> --json
+```
+
+Approving or rejecting requires a human session (`hepha login`), so an agent
+stops here and reports the pending approval to a person.
+
+## Command reference
+
+| Command                                                             | Notes                                                                    |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `hepha run "<prompt>"`                                              | `--repo --branch --task-type --model --harness --skill --title --follow` |
+| `hepha sessions list`                                               | `--status active\|waiting\|done --repo --search --page --limit --all`    |
+| `hepha sessions get\|logs\|send\|pause\|resume\|kill\|archive <id>` | `logs --after <sequence> --follow`, `kill --reason "…"`                  |
+| `hepha sessions checks\|pr\|verify <id>`                            | Re-run checks · CI status · proof artifacts                              |
+| `hepha questions list\|show\|answer\|cancel`                        | `list --session <id>`                                                    |
+| `hepha approvals list\|show\|approve\|reject`                       | `approve`/`reject` are human-session only                                |
+| `hepha repos \| branches <owner/repo> \| models \| skills`          | The catalog to read before creating a session                            |
+| `hepha keys list\|create\|revoke`                                   | Human-session only                                                       |
+| `hepha login \| logout \| whoami`                                   | `login` is interactive                                                   |
+
+Global flags: `--json` on every command that returns data, `--quiet` to drop
+the streamed transcript while following, `--version`, `--help`.
+
+## Common Mistakes
+
+### [CRITICAL] Retrying `hepha run` after exit 3
+
+Wrong:
+
+```bash
+hepha run "$PROMPT" --repo "$REPO" --follow || hepha run "$PROMPT" --repo "$REPO" --follow
+```
+
+Correct:
+
+```bash
+hepha run "$PROMPT" --repo "$REPO" --follow
+status=$?
+
+case "$status" in
+  0) ;;                              # delivered
+  3) hepha questions list --json ;;  # answer it, then follow again
+  *) exit "$status" ;;               # 1 failed · 2 usage — never remapped
+esac
+```
+
+Exit 3 means the existing session is parked on a question or a guardrail.
+Re-running creates a second session on the same repo while the first one waits
+forever.
+
+Source: apps/cli/src/lib/session-outcome.ts
+
+### [HIGH] Approving a guardrail with an API key
+
+Wrong:
+
+```bash
+export HEPHA_API_KEY=hepha_xxx
+hepha approvals approve "$GUARDRAIL_ID"
+```
+
+Correct:
+
+```bash
+hepha approvals show "$GUARDRAIL_ID" --json   # read it, then tell a human
+```
+
+`approvals:decide` is not a scope that exists — the route answers `403` to any
+key. `HEPHA_API_KEY` also takes precedence over a stored login, so a human
+whose shell exports it gets `403` on every human-only command until it is
+unset.
+
+Source: packages/server/src/routers/v1/approvals/router.ts (humanSessionMiddleware)
+
+### [HIGH] Parsing the human output instead of `--json`
+
+Wrong:
+
+```bash
+hepha sessions get "$ID" | grep -i "pr:" | awk '{print $2}'
+```
+
+Correct:
+
+```bash
+hepha sessions get "$ID" --json | jq -r '.prUrl // empty'
+```
+
+The aligned text is padded and coloured for a terminal. Under `--json` stdout
+is one parseable document, including failures — `{"ok":false,"error":{…}}`,
+with the exit code unchanged.
+
+Source: apps/cli/src/lib/output.ts
+
+### [HIGH] Re-reading the whole transcript on every poll
+
+Wrong:
+
+```bash
+while :; do hepha sessions logs "$ID" --json; sleep 5; done
+```
+
+Correct:
+
+```bash
+after=0
+while :; do
+  page=$(hepha sessions logs "$ID" --after "$after" --limit 200 --json)
+  after=$(jq -r "[$after, .nextCursor // 0, (.items[]?.sequence)] | max" <<<"$page")
+  [ "$(jq -r '.hasMore' <<<"$page")" = "true" ] || sleep 3
+done
+```
+
+Without `--after`, every poll re-downloads the transcript from the start and
+the consumer re-processes events it has already seen. Advance on the highest of
+both signals: `nextCursor` is `null` on the last page even when that page
+carried events, and an event the API cannot render is dropped from `items`
+while still consuming a sequence — following either one alone stalls the
+cursor or spins on the same page.
+
+Source: apps/cli/src/lib/follow.ts · packages/server/src/services/session-events-query.service.ts
+
+### [MEDIUM] Sending `--answers` as an object
+
+Wrong:
+
+```bash
+hepha questions answer "$BATCH" --answers '{"q_01":"2"}'
+```
+
+Correct:
+
+```bash
+hepha questions answer "$BATCH" --answers '[{"questionId":"q_01","selectedOptionIds":["2"]}]'
+```
+
+`--answers` takes a non-empty JSON **array** of `{questionId,
+selectedOptionIds?, freeText?}`, and an entry carrying neither an option nor
+free text answers nothing — both fail with exit 2 before any request is sent.
+
+Source: apps/cli/src/commands/collect-answers.ts
+
+### [MEDIUM] Creating a key without scopes, then writing with it
+
+Wrong:
+
+```bash
+hepha keys create "ci bot"
+export HEPHA_API_KEY=hepha_xxx
+hepha run "…" --repo "$REPO"      # 403
+```
+
+Correct:
+
+```bash
+hepha keys create "ci bot" --scope sessions:read --scope sessions:write \
+  --scope questions:read --scope questions:answer \
+  --scope approvals:read --scope catalog:read
+```
+
+A key created without `--scope` is read-only, and passing any scope **replaces**
+that default instead of adding to it — so the list has to carry everything the
+loop touches: write on sessions, both question scopes (a round nobody can answer
+parks forever) and `approvals:read`, without which the agent cannot even read
+the guardrail it is supposed to escalate.
+
+Source: packages/database/constants.ts · packages/server/src/routers/api-keys/mutations/create-api-key.ts