@mcp-com-ai/hapi 1.1.0 → 1.3.1

package/dist/skills/hapi-intent-based-apis/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: hapi-intent-based-apis
+description: Make an OpenAPI 3.x or Arazzo 1.1 contract AI-ready and intent-based so HAPI's runtime serves it as MCP tools that agents discover, call safely, and plan with — no code, only a better contract. Adds discoverable operations, MCP tool hints, x-hapi-intent/effects/capability/prerequisites, x-hapi-planning facts, x-hapi-client-facts, x-hapi-outcome, x-hapi-event, and planning-eligible Arazzo workflows, then verifies with hapi graph compile/audit/simulate and an MCP smoke test. Use whenever a user wants to make an API "intent-based", "agent-ready", or "AI-friendly", add capability graph or HCG metadata, fix tools the agent never finds or calls at the wrong time, reduce MCP context bloat with progressive discovery, or fix capability_plan results that always say clarification-required — even if they only say "enrich my spec", "annotate my OpenAPI for HAPI", or "why can't the agent book/cancel/update".
+license: MIT
+compatibility: Requires the HAPI CLI with the Capability Graph plugin (`hapi graph --help`) and Bun for the bundled checker. Arazzo checks need the Arazzo plugin (`hapi arazzo --help`).
+metadata:
+  author: mcp.com.ai agent-skills
+  version: "1.0.0"
+allowed-tools: Bash(hapi:*) Bash(bun:*) Bash(curl:*) Read Write Edit
+---
+
+# Enrich an API contract for intent-based agents
+
+An intent-based API tells an agent three things the raw OpenAPI document does
+not: **when** an operation is the right choice, **what it changes**, and **what
+must already be true** before it runs. HAPI turns that metadata into focused
+tool search, MCP tool hints, and a deterministic HAPI Capability Graph (HCG)
+that `capability_context` and `capability_plan` expose to any MCP client, such
+as OrcA in VS Code or an AI teammate like Clooney from Clawne Me.
+
+HAPI is code-less: if the API follows good practices, the contract is the
+whole integration. HAPI reads it at startup, serves every operation as an MCP
+tool, compiles the graph, and answers context and planning requests from it;
+OrcA and other MCP clients act on what it says. So every field is written for
+its **runtime effect** (`references/runtime-behavior.md`), and every statement
+must be **true for the API's behavior** as the contract, its documentation, and
+the domain owner describe it. Metadata that misstates behavior is worse than
+none: the planner trusts it.
+
+## Good API practices the contract must show
+
+- One operation per business action, with a stable `operationId`.
+- Searches/lists separate from selections and mutations; identifiers returned
+  by one operation and accepted by the next.
+- Meaningful status codes for business failures (409, 410, 422) with an error
+  body that names the next step.
+- `security` declared; servers declared (or `--url` for headless).
+- Descriptions written for the reader who must decide what to do next.
+
+## Inputs to collect
+
+- The OpenAPI 3.x document (and Arazzo 1.1 document, if any). Never overwrite
+  the original without permission; edit a copy or work on a branch.
+- What the API does, from the contract itself (paths, schemas, responses,
+  security, existing descriptions), its public documentation, and the domain
+  owner. Ask the owner only what the contract cannot say (which choices a
+  person makes, which actions need confirmation, which errors mean "pick
+  again"). Mark anything you infer as an assumption in the report.
+- The users' language and the business narrative: who the actors are, which
+  choices people make, which actions need confirmation.
+
+If the document is invalid, stop and report the validator output first.
+
+## Workflow
+
+### 1. Inventory operations and the business journey
+
+Run the checker to get a baseline, then read each operation:
+
+```bash
+bun <skill-dir>/scripts/check-intent-metadata.ts ./openapi.yaml
+```
+
+For each operation record what it reads or changes, which inputs must come
+from an earlier result or a person, which declared errors force a new
+decision, whether repeating it is safe, who may call it (`security`), and
+whether it notifies anyone (webhooks, callbacks). Where the contract is silent,
+use the API documentation or ask the owner; never guess effects.
+
+Build the domain table before writing YAML:
+
+| Operation | Kind (search / select / mutate) | Requires | Produces | Removes | Failure outcomes |
+
+An empty selection step in front of a mutation is a gap: either the API has a
+selection operation or a person makes the choice (a client fact).
+
+### 2. Make every operation discoverable
+
+HAPI search matches tool names, descriptions, and arguments, word by word.
+OrcA lists each deferred tool by name with the first sentence of its
+description (about 80 characters) so the model knows the tool exists.
+
+- Stable, verb-first, unique `operationId` (it becomes the tool name).
+- `summary` starts with the action and the business object, in the users'
+  language. Add the users' own terms when the API language differs.
+- First description sentence: what it does, for whom. Following sentences:
+  where inputs come from ("Use the `slotId` returned by getAvailability"),
+  limits, and what not to do.
+- Every parameter and body property says the source of its value.
+- Never rename an `operationId` that clients already use without telling the user.
+
+### 3. Set MCP tool hints that match behavior
+
+HAPI derives MCP annotations only from `x-readOnlyHint`, `x-destructiveHint`,
+`x-idempotentHint`, and `x-openWorldHint`; otherwise `GET` is read-only and
+`POST`/`PUT`/`PATCH`/`DELETE` are destructive. Clients such as OrcA ask for
+confirmation before any tool that is not read-only, so set hints explicitly
+when the method misleads (search via `POST`, non-destructive create, idempotent
+`PUT`). Base each hint on what the operation does, not on its HTTP method.
+
+### 4. Add discovery semantics
+
+Add `x-hapi-capability`, `x-hapi-intent`, `x-hapi-effects`, and
+`x-hapi-prerequisites` (exact shapes and validation in
+`references/extension-rules.md`):
+
+- `x-hapi-capability`: one or more taxonomy paths (`Domain/Area/Action`).
+- `x-hapi-intent.use-when` / `avoid-when`: concrete situations that separate
+  similar operations (book vs reschedule, search vs list mine).
+- `x-hapi-effects.mode` ∈ `read | create | update | delete | action`, plus
+  `side-effecting`, `destructive`, `idempotent`, `requires-confirmation` as the
+  API documents them. `requires-confirmation: true` adds the `mutation-confirmation` gate.
+- `x-hapi-prerequisites`: human-readable readiness. It never creates machine state.
+
+### 5. Model business state with `x-hapi-planning`
+
+- Facts are lowercase canonical predicates (`^[a-z][a-z0-9]*([._-][a-z0-9]+)*$`)
+  describing **verified business state**: `slot.selected`, `appointment.booked`.
+  Never commands (`bookAppointment`), wishes (`user.wants.x`), or guesses.
+- A search produces `<things>.consulted`; it **never** produces `<thing>.selected`.
+- `produces` is required and non-empty; `cost` defaults to 1 and must be finite
+  and ≥ 0; no duplicates; a fact cannot be both produced and removed.
+- Cancellations/deletions `remove` the state they end.
+- Cross-domain `requires` only for real business rules the owner confirms.
+- Never invent transitions from prose or HTTP verbs; HAPI never does either.
+
+### 6. Declare facts only people can establish
+
+At the document root, add `x-hapi-client-facts` for selections, confirmations,
+and identity checks that happen in the conversation. Each `description` says
+who establishes it and how (for example, identity from the chat channel).
+Declaring a fact never makes it true; the client still verifies it.
+
+### 7. Declare failure outcomes and events
+
+- For each declared non-2xx response that forces a new decision (409
+  unavailable, 410 expired, 422 rule violation; not 400, 401/403, or 5xx),
+  add `x-hapi-outcome` with `produces`/`removes`. Status key: a status code,
+  `NXX`, or `default`, never `2xx`. The operation must have `x-hapi-planning`.
+  Update the response `description` to name the next question to ask.
+- For OpenAPI 3.1 `webhooks`/`callbacks` the API documents, add
+  `x-hapi-event.produces`. Never on ordinary `paths` operations.
+
+### 8. Arazzo workflows (when present)
+
+Give a workflow `x-hapi-planning` only when it is one atomic business
+transition: resolved OpenAPI steps only, no nested workflows, no dynamic
+success/failure branching. Derive its facts from its steps: `requires` = step
+requirements no earlier step produces; `produces` = every step's produced fact
+(plus an aggregate if useful); `removes` = every removed fact. Validate with
+`hapi arazzo validate --strict`. For several APIs, use the `hapi-federated-apis` skill.
+
+### 9. Verify, then iterate
+
+```bash
+bun <skill-dir>/scripts/check-intent-metadata.ts ./openapi.yaml
+hapi graph compile ./openapi.yaml --out graph.json
+hapi graph audit graph.json
+hapi graph simulate graph.json --initial-fact <client facts…> --goal-fact <goal> \
+  --satisfied-gate mutation-confirmation --eligible-operation <operationId>
+hapi graph visualize graph.json --goal-fact <goal> --out flow.html --initial-view flow-cards
+```
+
+- `compile` fails with pointer-scoped errors on malformed metadata; fix them all.
+- `audit` must report no orphan requirements and every intended goal `planned`
+  (exit 0). Document intentional gaps.
+- `simulate` each important goal three ways: nothing verified
+  (`clarification-required`), all facts and gates (`planned`), already true (`complete`).
+- Optionally smoke-test the MCP surface:
+  `hapi serve --specs ./openapi.yaml --capability-graph --capability-planning --dev`
+  then call `tool_search` and `capability_context` with real user phrasing in
+  the users' language (see `references/examples.md`).
+
+### 10. Report
+
+Return: the changed file path; a per-operation table of what you added and why
+(its runtime effect); the fact vocabulary (client facts, outcomes, goals); audit and
+simulation results; assumptions that need the owner's confirmation; and any
+`operationId` or response change that affects existing clients.
+
+## Guardrails
+
+- Do not fabricate security, business policy, operations, or Links to make a
+  graph connect. Report the gap instead.
+- Never add a Link that maps a search result into a selection input; selection
+  is a person's decision.
+- Keep metadata in the source contract, not in a generated derivative; if the
+  project generates JSON from YAML, regenerate it.
+- No secrets, real customer data, or production identifiers in examples.
+- Do not ask for or rely on implementation code; improve the contract. When the
+  API itself breaks good practice (no stable IDs, no selection operation,
+  errors without status codes), report it as an API design gap.
+
+## Files
+
+- `references/extension-rules.md` — exact shapes, defaults, and compiler diagnostics.
+- `references/runtime-behavior.md` — what HAPI's runtime and OrcA do with each contract element.
+- `references/examples.md` — a full before/after operation, client facts, outcome, Arazzo workflow, and smoke-test calls.
+- `scripts/check-intent-metadata.ts` — static checker (exit 1 on errors).

package/dist/skills/hapi-intent-based-apis/references/examples.md

@@ -0,0 +1,135 @@
+# Examples (clinic appointments)
+
+## Before
+
+```yaml
+paths:
+  /appointments:
+    post:
+      operationId: createAppt
+      summary: Create
+      requestBody: { $ref: "#/components/requestBodies/Appt" }
+      responses:
+        "201": { description: Created }
+        "409": { description: Conflict }
+```
+
+## After
+
+```yaml
+x-hapi-client-facts:
+  - predicate: patient.identity.verified
+    description: The phone number comes from the chat channel, never from typed text.
+  - predicate: professional.selected
+    description: The patient picked one professional from searchProfessionals results.
+  - predicate: slot.selected
+    description: The patient picked one free slot from getAvailability results.
+  - predicate: appointment.details.confirmed
+    description: The patient confirmed the appointment summary.
+
+paths:
+  /appointments:
+    post:
+      operationId: bookAppointment
+      summary: Book an appointment for the patient
+      description: |
+        Books a confirmed appointment in the selected professional's free slot.
+        Use the `slotId` returned by getAvailability; a constructed value returns `400`.
+      x-destructiveHint: false
+      x-idempotentHint: false
+      x-hapi-capability: [Healthcare/Appointments/Booking]
+      x-hapi-intent:
+        use-when:
+          - The patient selected a professional and a free slot and confirmed the details.
+        avoid-when:
+          - The patient only wants to see free slots or existing appointments.
+          - The patient wants to move an existing appointment (use rescheduleAppointment).
+      x-hapi-effects:
+        mode: create
+        side-effecting: true
+        destructive: false
+        idempotent: false
+        requires-confirmation: true
+      x-hapi-prerequisites:
+        - The patient identity, the professional, and the slot are verified.
+      x-hapi-planning:
+        requires:
+          - predicate: patient.identity.verified
+          - predicate: professional.selected
+          - predicate: slot.selected
+          - predicate: appointment.details.confirmed
+        produces:
+          - predicate: appointment.booked
+        cost: 1
+      responses:
+        "201":
+          description: Appointment booked; relay `mensaje` to the patient.
+        "409":
+          description: The slot was taken; ask the patient to pick another slot.
+          x-hapi-outcome:
+            produces: [{ predicate: slot.unavailable }]
+            removes: [{ predicate: slot.selected }]
+```
+
+## Search vs selection
+
+```yaml
+  /professionals/search:
+    post:
+      operationId: searchProfessionals
+      summary: Search verified professionals by specialty or name
+      x-readOnlyHint: true
+      x-destructiveHint: false
+      x-idempotentHint: true
+      x-hapi-effects: { mode: read }
+      x-hapi-planning:
+        produces: [{ predicate: professionals.consulted }]
+```
+
+## Cancellation removes state
+
+```yaml
+      x-hapi-planning:
+        requires:
+          - predicate: patient.identity.verified
+          - predicate: appointment.selected
+          - predicate: cancellation.confirmed
+        produces: [{ predicate: appointment.cancelled }]
+        removes: [{ predicate: appointment.booked }]
+```
+
+## Planning-eligible Arazzo workflow
+
+```yaml
+workflows:
+  - workflowId: bookAndNotify
+    x-hapi-planning:
+      requires:
+        - predicate: patient.identity.verified
+        - predicate: professional.selected
+        - predicate: slot.selected
+        - predicate: appointment.details.confirmed
+      produces:
+        - predicate: appointment.booked
+        - predicate: patient.notified
+    steps:
+      - stepId: book
+        operationId: $sourceDescriptions.clinic.bookAppointment
+      - stepId: notify
+        operationId: $sourceDescriptions.clinic.sendConfirmation
+```
+
+## Smoke test (MCP over Streamable HTTP)
+
+```bash
+hapi serve --specs ./clinic.openapi.yaml --capability-graph --capability-planning --dev --port 3000
+```
+
+Then, with any MCP client (or curl with `initialize` → `notifications/initialized` → `tools/call`):
+
+- `tool_search` `{ "query": "<a real user sentence in the users' language>" }` → expect the right operations in the top results.
+- `capability_context` `{ "query": "<same sentence>" }` → expect the goal (`appointment.booked`) and `clientEstablished: true` on client facts.
+- `capability_plan` `{ "initialFacts": [], "goalFacts": [{ "predicate": "appointment.booked" }] }` → `clarification-required` listing the missing client facts.
+
+Search matches words: if English phrasing returns nothing for a Spanish API,
+add the users' terms to summaries/descriptions and test again.

package/dist/skills/hapi-intent-based-apis/references/extension-rules.md

@@ -0,0 +1,90 @@
+# Extension rules (as enforced by the HAPI compiler)
+
+Malformed **supported** extensions fail `hapi graph compile` and graph-mode
+`hapi serve` startup with a pointer-scoped diagnostic. Missing semantics are
+inferred deterministically from OpenAPI (tags, summary, method, security,
+Links) and keep provenance; explicit metadata always wins.
+
+## Operation extensions
+
+| Extension | Shape | Diagnostics |
+| --- | --- | --- |
+| `x-hapi-capability` | non-empty string, or non-empty array of non-empty strings | `invalid-capability` |
+| `x-hapi-intent` | object with only `use-when` and `avoid-when`, each an array of non-empty strings | `invalid-intent` |
+| `x-hapi-effects` | object: `mode` (required) ∈ `read, create, update, delete, action`; optional booleans `side-effecting`, `destructive`, `idempotent`, `requires-confirmation`; no other keys | `invalid-effects` |
+| `x-hapi-prerequisites` | array of non-empty strings | `invalid-prerequisites` |
+| `x-hapi-planning` | object with only `requires`, `produces`, `removes`, `cost` | `invalid-planning`, `invalid-planning-field`, `invalid-planning-produces`, `invalid-planning-facts`, `invalid-planning-fact`, `duplicate-planning-fact`, `invalid-planning-cost`, `conflicting-planning-fact` |
+
+`mode: write` is **not** valid (use `create`, `update`, or `action`).
+
+### Effect defaults by mode (when a boolean is omitted)
+
+| mode | side-effecting | destructive | idempotent | requires-confirmation |
+| --- | --- | --- | --- | --- |
+| read | false | false | true | false |
+| create | true | false | false | false |
+| update | true | false | false | false |
+| delete | true | true | true | true |
+| action | true | false | false | false |
+
+Without `x-hapi-effects`, the method decides: GET/HEAD/OPTIONS → read, POST →
+create, DELETE → delete, PUT/PATCH → update (PUT idempotent).
+
+## Facts
+
+- Shape: `{ predicate: string, value?: JSON }`, no other keys.
+- Predicate pattern: `^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$`.
+- Values must be JSON-safe (no functions, cycles, non-finite numbers).
+- No duplicate fact in a list; nothing both produced and removed.
+- `produces` must be non-empty. `cost` defaults to 1, finite and ≥ 0.
+- Compiler-generated `operation.<id>.completed` facts exist; do not author them.
+
+## Document root
+
+`x-hapi-client-facts`: array of `{ predicate, value?, description? }` with the
+fact rules (`invalid-client-facts`). A declared fact no transition requires
+compiles with an `unused-client-fact` warning.
+
+## Responses
+
+`x-hapi-outcome` on a response object: only `produces` and/or `removes` (at least
+one non-empty, same fact rules, no conflicts). Status key: code, `NXX`, or
+`default`; never `2xx` (`outcome-on-success-response`). Needs operation
+`x-hapi-planning`, otherwise ignored with `outcome-without-planning`.
+Diagnostics: `invalid-outcome`, `invalid-outcome-field`, `empty-outcome`,
+`conflicting-outcome-fact`. The planner never plans through an outcome; plan
+steps list them, flow cards show them as "Otherwise", audit lists them as
+response facts.
+
+## Webhooks and callbacks
+
+`x-hapi-event: { produces: [facts] }` (non-empty) on OpenAPI 3.1 `webhooks` or
+operation `callbacks` only. On `paths` operations it is ignored
+(`event-on-path-operation`); unresolvable references are skipped
+(`unresolved-trigger`). Triggers are descriptive: HAPI never subscribes or plans
+through them.
+
+## MCP tool hints (HAPI core)
+
+`x-readOnlyHint`, `x-destructiveHint`, `x-idempotentHint`, `x-openWorldHint`
+(boolean or "true"/"false"). If none is set: GET → read-only, non-destructive;
+POST/PUT/PATCH/DELETE → not read-only, destructive. `x-openWorldHint` defaults
+to true in `--headless` mode unless `--no-open-world`.
+
+## Arazzo workflow planning
+
+`x-hapi-planning` on a workflow uses the same shape. Not eligible (warning
+`unsupported-arazzo-planning-workflow`) when the workflow has no resolved
+OpenAPI steps, invokes nested workflows, or uses dynamic success/failure
+control flow. Consistency warnings (failures under `hapi arazzo validate --strict`):
+steps without valid planning, step requirements the workflow does not require,
+step productions the workflow does not declare, declared removals that steps
+leave present. Gates come from step security, destructive effects, and
+`requires-confirmation`.
+
+## Gates and plan outcomes
+
+Gates: `operation-authorization` (from security), `mutation-confirmation`
+(destructive or requires-confirmation). Outcomes: `complete`, `planned`,
+`clarification-required`, `unplannable`. Audit exit codes: 0 clean, 1 gaps,
+2 usage/compile error.

package/dist/skills/hapi-intent-based-apis/references/runtime-behavior.md

@@ -0,0 +1,52 @@
+# How HAPI and OrcA use each piece of the contract
+
+The contract is the program. HAPI reads it at startup and serves MCP tools from
+it; there is no glue code to write. Every field below changes what the runtime
+does, so write each one for its runtime effect.
+
+## HAPI runtime (`hapi serve`)
+
+| Contract element | Runtime effect |
+| --- | --- |
+| `operationId` | MCP tool name; stable identity in the capability graph, plans, and OrcA Traffic. |
+| `summary`, `description` | Tool description; matched word by word by `tool_search` and graph discovery. |
+| parameters, request body, schemas | Tool `inputSchema`; HAPI validates arguments and builds the upstream HTTP request from them. Descriptions tell the model where each value comes from. |
+| responses (+ descriptions) | What the tool returns and how errors read to the model; response descriptions are the model's instructions for the next turn. |
+| `security` | Upstream authentication, and the `operation-authorization` gate; authorization filtering happens before any ranking. |
+| `servers` / `--url` | Where calls go (`--headless --url` for an existing backend). |
+| `x-readOnlyHint`, `x-destructiveHint`, `x-idempotentHint`, `x-openWorldHint` | MCP tool annotations. Without them: GET read-only, POST/PUT/PATCH/DELETE destructive. Clients decide confirmations from these. |
+| `--deferred-tool-search` | Tools sent with `defer_loading: true`; a `tool_search` tool returns the relevant ones. Smaller context. |
+| `--capability-graph` | Compiles the contract into the HAPI Capability Graph (implies deferred search with graph-aware ranking). Malformed `x-hapi-*` metadata fails startup. |
+| `x-hapi-capability` | Taxonomy used for discovery and grouping. |
+| `x-hapi-intent` | `use-when`/`avoid-when` evidence for ranking and disambiguation in context results. |
+| `x-hapi-effects` | Effect mode and flags; destructive or `requires-confirmation` add the `mutation-confirmation` gate. |
+| `x-hapi-prerequisites` | Human-readable readiness shown in context; never machine state. |
+| `x-hapi-planning` | A planning transition: requires/produces/removes facts with a cost. The only way (with valid Links and eligible Arazzo workflows) to create one; HAPI never infers transitions from prose or verbs. |
+| `x-hapi-client-facts` | Requirement cards marked `clientEstablished: true` in `capability_context`; audit treats them as established outside the API. Never makes a fact true. |
+| `x-hapi-outcome` | Listed on plan steps as alternatives ("Otherwise" in flow cards); the client re-plans after verifying the response. |
+| webhooks/callbacks + `x-hapi-event` | Descriptive triggers; HAPI never subscribes. |
+| OpenAPI Links (fully mapped) | Planning-eligible transitions between operations; never map a search result into a selection input. |
+| Arazzo workflows (+ `x-hapi-planning`) | One MCP tool per workflow that runs every step; eligible workflows become one atomic planning transition. |
+| `--capability-planning` | Adds read-only `capability_context` (request → candidate goals, facts, gates, tools) and `capability_plan` (verified facts + goal → steps, missing facts, unsatisfied gates). Neither calls the API. |
+| `--runtime-authority guarded` | Adds plan execution with revalidation and trusted confirmation receipts (advanced, opt-in). |
+
+## OrcA (VS Code harness for MCP and API work)
+
+| Contract element | What OrcA does with it |
+| --- | --- |
+| `tool_search` + `defer_loading` | Progressive discovery: sends a `search_tools` tool and always-loaded tools; loads deferred tools per message and on demand. |
+| tool names + first description sentence | A catalog of not-yet-loaded tools inside `search_tools` (names, ~80-char purpose), so the model knows they exist. |
+| `capability_context` | Asked with each user message; results fill the **Context** tab and the tools they name are loaded automatically. |
+| `capability_plan` | **Plan This Goal** in the Context tab with the facts the user verified. |
+| read-only hint | Default confirmation policy asks before any tool that is not read-only. |
+| response descriptions, outcomes | Shown in chat and Traffic; guide the next question. |
+| `operationId` | **Open Operation in Contract** jumps from a Traffic frame to the operation. |
+
+## Consequences for authors
+
+- A vague summary hides a tool from search; the agent then says it "has no access".
+- A missing read-only hint on a POST search makes every search ask for confirmation.
+- A requirement nobody produces and nobody declares as a client fact makes every
+  plan for that goal `clarification-required`.
+- A search that "produces" a selection lets the agent pick for the user.
+- A 409 without an outcome leaves the agent retrying instead of asking again.

package/dist/skills/hapi-intent-based-apis/scripts/check-intent-metadata.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env bun
+/**
+ * Static checks for intent-based HAPI metadata in an OpenAPI 3.x document.
+ * Complements (does not replace) `hapi graph compile` and `hapi graph audit`.
+ * Usage: bun check-intent-metadata.ts <openapi.yaml|json> [--json]
+ * Exit 1 on errors.
+ */
+import { readFileSync } from 'node:fs';
+
+type Level = 'error' | 'warning' | 'info';
+interface Finding { level: Level; where: string; rule: string; message: string }
+type Obj = Record<string, any>;
+
+const METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+const MODES = new Set(['read', 'create', 'update', 'delete', 'action']);
+const EFFECT_KEYS = new Set(['mode', 'side-effecting', 'destructive', 'idempotent', 'requires-confirmation']);
+const PREDICATE = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const COMMAND_LIKE = /^(get|list|create|update|delete|book|cancel|search|find|add|remove|send|post|put)[A-Z_.]/;
+const WISH = /\b(wants|wishes|intends|desires|requested)\b/;
+
+function load(file: string): Obj {
+  const text = readFileSync(file, 'utf8');
+  if (/\.json$/i.test(file)) return JSON.parse(text);
+  const yaml = (Bun as any).YAML;
+  if (!yaml?.parse) throw new Error('This Bun version has no YAML parser; convert the document to JSON first.');
+  return yaml.parse(text);
+}
+
+const isObj = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+const nonEmptyStrings = (v: unknown) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.trim() !== '');
+
+function checkFacts(list: unknown, where: string, add: (l: Level, w: string, r: string, m: string) => void): string[] {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) {
+    add('error', where, 'facts', 'Facts must be an array.');
+    return [];
+  }
+  const keys: string[] = [];
+  for (const fact of list) {
+    if (!isObj(fact) || typeof fact.predicate !== 'string' || Object.keys(fact).some((k) => k !== 'predicate' && k !== 'value' && k !== 'description')) {
+      add('error', where, 'fact-shape', 'Each fact is { predicate, value? }.');
+      continue;
+    }
+    if (!PREDICATE.test(fact.predicate)) add('error', where, 'predicate', `"${fact.predicate}" must match ${PREDICATE}.`);
+    if (COMMAND_LIKE.test(fact.predicate)) add('warning', where, 'fact-is-command', `"${fact.predicate}" looks like a command; use business state.`);
+    if (WISH.test(fact.predicate.replace(/[._-]/g, ' '))) add('warning', where, 'fact-is-wish', `"${fact.predicate}" looks like a wish, not verified state.`);
+    const key = JSON.stringify([fact.predicate, fact.value]);
+    if (keys.includes(key)) add('error', where, 'duplicate-fact', `Duplicate fact "${fact.predicate}".`);
+    keys.push(key);
+  }
+  return list.filter(isObj).map((f) => f.predicate as string);
+}
+
+function checkOperation(op: Obj, method: string, path: string, add: (l: Level, w: string, r: string, m: string) => void, state: { produced: Set<string>; required: Map<string, string[]>; ids: Map<string, string> }) {
+  const where = `${method.toUpperCase()} ${path}`;
+  const id: string | undefined = op.operationId;
+  if (!id) add('error', where, 'operationId', 'Missing operationId (it becomes the tool name).');
+  else if (state.ids.has(id)) add('error', where, 'operationId', `Duplicate operationId "${id}" (also ${state.ids.get(id)}).`);
+  else state.ids.set(id, where);
+  const label = id ?? where;
+  if (!op.summary?.trim()) add('error', label, 'summary', 'Missing summary (drives search and the tool catalog).');
+  else if (op.summary.trim().split(/\s+/).length < 3) add('warning', label, 'summary', `Summary "${op.summary}" is too generic for search.`);
+  if (!op.description?.trim()) add('warning', label, 'description', 'No description: say what it does and where inputs come from.');
+  for (const p of op.parameters ?? []) if (isObj(p) && !p.$ref && !p.description) add('warning', label, 'parameter', `Parameter "${p.name}" has no description of its source.`);
+
+  const effects = op['x-hapi-effects'];
+  if (effects === undefined) add('warning', label, 'effects', 'No x-hapi-effects; the method decides (POST = create).');
+  else if (!isObj(effects) || !MODES.has(effects.mode) || Object.keys(effects).some((k) => !EFFECT_KEYS.has(k)) || Object.entries(effects).some(([k, v]) => k !== 'mode' && typeof v !== 'boolean')) {
+    add('error', label, 'effects', 'x-hapi-effects needs mode ∈ read|create|update|delete|action and only boolean flags.');
+  }
+  const readMode = isObj(effects) && effects.mode === 'read';
+  const hintRead = op['x-readOnlyHint'] === true || op['x-readOnlyHint'] === 'true';
+  if (readMode && method !== 'get' && method !== 'head' && !hintRead) add('error', label, 'tool-hint', `Read-only ${method.toUpperCase()} without x-readOnlyHint: true; clients will ask for confirmation on every call.`);
+  if (isObj(effects) && effects.mode === 'create' && method === 'post' && op['x-destructiveHint'] === undefined) add('warning', label, 'tool-hint', 'Create via POST is annotated destructive by default; set x-destructiveHint: false if nothing is lost.');
+
+  const cap = op['x-hapi-capability'];
+  if (cap === undefined) add('warning', label, 'capability', 'No x-hapi-capability taxonomy.');
+  else if (!(typeof cap === 'string' && cap.trim()) && !(nonEmptyStrings(cap) && cap.length)) add('error', label, 'capability', 'x-hapi-capability must be a non-empty string or array.');
+  const intent = op['x-hapi-intent'];
+  if (intent === undefined) add('warning', label, 'intent', 'No x-hapi-intent use-when/avoid-when.');
+  else if (!isObj(intent) || Object.keys(intent).some((k) => k !== 'use-when' && k !== 'avoid-when') || (intent['use-when'] && !nonEmptyStrings(intent['use-when'])) || (intent['avoid-when'] && !nonEmptyStrings(intent['avoid-when']))) add('error', label, 'intent', 'x-hapi-intent accepts only use-when/avoid-when string arrays.');
+  const pre = op['x-hapi-prerequisites'];
+  if (pre !== undefined && !nonEmptyStrings(pre)) add('error', label, 'prerequisites', 'x-hapi-prerequisites must be an array of non-empty strings.');
+  if (op['x-hapi-event'] !== undefined) add('warning', label, 'event', 'x-hapi-event on a paths operation is ignored; use webhooks/callbacks.');
+
+  const planning = op['x-hapi-planning'];
+  if (planning === undefined) {
+    add('info', label, 'planning', 'No x-hapi-planning: discovery-only operation.');
+  } else if (!isObj(planning) || Object.keys(planning).some((k) => !['requires', 'produces', 'removes', 'cost'].includes(k))) {
+    add('error', label, 'planning', 'x-hapi-planning accepts only requires, produces, removes, cost.');
+  } else {
+    const requires = checkFacts(planning.requires, label, add);
+    const produces = checkFacts(planning.produces, label, add);
+    const removes = checkFacts(planning.removes, label, add);
+    if (!produces.length) add('error', label, 'planning-produces', 'produces must be non-empty.');
+    if (planning.cost !== undefined && (typeof planning.cost !== 'number' || !Number.isFinite(planning.cost) || planning.cost < 0)) add('error', label, 'planning-cost', 'cost must be finite and ≥ 0.');
+    for (const p of produces) if (removes.includes(p)) add('error', label, 'conflicting-fact', `"${p}" is both produced and removed.`);
+    if (readMode) for (const p of produces) if (/\.selected$/.test(p)) add('error', label, 'search-selects', `A read operation produces "${p}"; selections are a person's choice (client fact).`);
+    if (isObj(effects) && effects.mode === 'delete' && !removes.length) add('warning', label, 'removes', 'Delete operation removes no fact; does it end some state?');
+    produces.forEach((p) => state.produced.add(p));
+    requires.forEach((r) => state.required.set(r, [...(state.required.get(r) ?? []), label]));
+  }
+  for (const [status, response] of Object.entries(op.responses ?? {})) {
+    if (!isObj(response) || response['x-hapi-outcome'] === undefined) continue;
+    const outcome = response['x-hapi-outcome'];
+    const at = `${label} ${status}`;
+    if (/^2/.test(status)) add('error', at, 'outcome-on-success', 'x-hapi-outcome is not allowed on 2xx responses.');
+    if (planning === undefined) add('warning', at, 'outcome-without-planning', 'Ignored: the operation has no x-hapi-planning.');
+    if (!isObj(outcome) || Object.keys(outcome).some((k) => k !== 'produces' && k !== 'removes')) {
+      add('error', at, 'outcome', 'x-hapi-outcome accepts only produces/removes.');
+      continue;
+    }
+    const p = checkFacts(outcome.produces, at, add);
+    const r = checkFacts(outcome.removes, at, add);
+    if (!p.length && !r.length) add('error', at, 'empty-outcome', 'Outcome needs produces or removes.');
+    p.forEach((f) => state.produced.add(f));
+  }
+}
+
+export function check(doc: Obj) {
+  const findings: Finding[] = [];
+  const add = (level: Level, where: string, rule: string, message: string) => findings.push({ level, where, rule, message });
+  const state = { produced: new Set<string>(), required: new Map<string, string[]>(), ids: new Map<string, string>() };
+  if (!String(doc.openapi ?? '').startsWith('3.')) add('error', 'document', 'openapi', 'Expected an OpenAPI 3.x document.');
+  for (const [path, item] of Object.entries(doc.paths ?? {})) {
+    if (!isObj(item)) continue;
+    for (const method of METHODS) if (isObj(item[method])) checkOperation(item[method], method, path, add, state);
+  }
+  for (const [name, item] of Object.entries(doc.webhooks ?? {})) {
+    if (!isObj(item)) continue;
+    for (const method of METHODS) {
+      const ev = item[method]?.['x-hapi-event'];
+      if (ev === undefined) continue;
+      const facts = isObj(ev) ? checkFacts(ev.produces, `webhook ${name}`, add) : [];
+      if (!facts.length) add('error', `webhook ${name}`, 'event', 'x-hapi-event.produces must be a non-empty fact array.');
+      facts.forEach((f) => state.produced.add(f));
+    }
+  }
+  const clientFacts = checkFacts(doc['x-hapi-client-facts'], 'x-hapi-client-facts', add);
+  for (const fact of doc['x-hapi-client-facts'] ?? []) if (isObj(fact) && !fact.description) add('warning', 'x-hapi-client-facts', 'client-fact-description', `"${fact.predicate}" has no description of who establishes it.`);
+  for (const fact of clientFacts) if (!state.required.has(fact)) add('warning', 'x-hapi-client-facts', 'unused-client-fact', `"${fact}" is not required by any operation.`);
+  for (const [fact, by] of state.required) {
+    if (!state.produced.has(fact) && !clientFacts.includes(fact)) add('error', fact, 'orphan-requirement', `Required by ${by.join(', ')} but never produced and not a client fact.`);
+  }
+  return { findings, operations: state.ids.size };
+}
+
+if (import.meta.main) {
+  const file = process.argv[2];
+  if (!file) {
+    console.error('Usage: bun check-intent-metadata.ts <openapi.yaml|json> [--json]');
+    process.exit(2);
+  }
+  const { findings, operations } = check(load(file));
+  if (process.argv.includes('--json')) console.log(JSON.stringify({ operations, findings }, null, 2));
+  else {
+    const icon = { error: '✗', warning: '!', info: '·' } as const;
+    for (const f of findings) console.log(`${icon[f.level]} [${f.rule}] ${f.where}: ${f.message}`);
+    const count = (l: Level) => findings.filter((f) => f.level === l).length;
+    console.log(`${operations} operation(s) · ${count('error')} error(s) · ${count('warning')} warning(s) · ${count('info')} info`);
+  }
+  process.exit(findings.some((f) => f.level === 'error') ? 1 : 0);
+}

package/dist/workspace-plugins.d.ts

@@ -7,4 +7,4 @@
  * third-party plugins should not appear — those are discovered through
  * `$HAPI_HOME/config.json#plugins` or the known-plugins registry.
  */
-export declare const WORKSPACE_PLUGINS: readonly ["@mcp-com-ai/plugin-openapi", "@mcp-com-ai/plugin-arazzo", "@mcp-com-ai/plugin-cloudflare", "@mcp-com-ai/plugin-otel"];
+export declare const WORKSPACE_PLUGINS: readonly ["@mcp-com-ai/plugin-openapi", "@mcp-com-ai/plugin-arazzo", "@mcp-com-ai/plugin-cloudflare", "@mcp-com-ai/plugin-otel", "@mcp-com-ai/plugin-capability-graph"];