skillscript-runtime 0.9.6 → 0.9.8

package/examples/connectors/HttpWebhookAgentConnector/HttpWebhookAgentConnector.ts

@@ -0,0 +1,320 @@
+/**
+ * HttpWebhookAgentConnector — example AgentConnector for HTTP-webhook substrates.
+ *
+ * This is the canonical worked example for adopter agents writing their own
+ * AgentConnector against an HTTP substrate. It's intentionally readable + small,
+ * not feature-complete. Adopters fork this directory into their own codebase
+ * and customize per their substrate's specifics.
+ *
+ * What it does:
+ *   - Maps `agent_id` → URL via JSON config (per audit v0.9.7 Q6).
+ *   - POSTs DeliveryPayload (with `agent_id` at top-level for receiver routing)
+ *     as JSON to the configured URL.
+ *   - Synthesizes a DeliveryReceipt from the HTTP response (substrate-specific
+ *     response shapes are translated here, not assumed canonical).
+ *   - health_check() pings configured agents (or returns true if none configured).
+ *   - wake() throws if no wake URL configured for the agent.
+ *   - agent_status?() not implemented (optional per contract).
+ *   - request_response() throws NotImplementedError until v0.10 exchange() ships.
+ *
+ * Deployment models the wire format supports without code changes:
+ *   - Model A: one URL per agent_id. Routing decided by URL (different hosts /
+ *     ports / paths). Adopter runs multiple receivers or one with URL-distinguished
+ *     routing.
+ *   - Model B: single URL, router receiver. Agent_id lives in the POST body;
+ *     receiver inspects + dispatches. Cleaner when adopter already has a
+ *     routing layer.
+ *   - Model C: variable-driven channel selection IN THE SKILL —
+ *     `notify(agent="agent-${CHANNEL}", ...)` — works on top of A or B.
+ *
+ * Auth: no auth by default. Bearer-token and HMAC-SHA256 paths are stubbed +
+ * commented; adopters enable per their threat model.
+ *
+ * What it deliberately doesn't do (fork to add):
+ *   - Retry on 5xx — fail-fast; adopters' retry semantics differ per substrate.
+ *   - Multi-region failover URLs per agent.
+ *   - OAuth flows, mTLS, SAML — adopter-specific auth providers.
+ *   - Streaming / chunked deliveries (HTTP/2 push, websockets).
+ *   - Async-callback reply pattern for request_response() (v0.10 design choice).
+ */
+
+// Adopters who fork this example: replace these relative imports with
+// `import type { ... } from "skillscript-runtime/connectors";`
+import type {
+  AgentConnector,
+  AgentDescriptor,
+  DeliveryPayload,
+  DeliveryReceipt,
+  RequestResponseOpts,
+  Response as AgentResponse,
+  WakeOpts,
+  WakeReceipt,
+} from "../../../src/connectors/agent.js";
+import type { StaticCapabilities } from "../../../src/connectors/types.js";
+
+/** Per-agent config — `url` required; `wake_url` + `status_url` optional. */
+export interface HttpWebhookAgentConfig {
+  url: string;
+  wake_url?: string;
+  status_url?: string;
+}
+
+/** Connector construction options — all derivable from `.env`. */
+export interface HttpWebhookAgentConnectorOptions {
+  /** Map of agent_id → per-agent config. Required; empty map means no agents wired. */
+  agents: Record<string, HttpWebhookAgentConfig>;
+  /** Per-request timeout in ms (total request duration via AbortSignal.timeout). Default 5000. */
+  timeout_ms?: number;
+  /**
+   * `Authorization` header value (e.g., `"Bearer abc123"`). When set, every
+   * outbound POST includes `Authorization: <value>`. Can be combined with
+   * `hmac_secret` for auth + body-integrity; most adopters need only one.
+   */
+  authorization?: string;
+  /**
+   * HMAC-SHA256 secret. When set, every outbound POST is signed:
+   * `X-Signature: sha256=<hex(HMAC_SHA256(secret, raw_body))>`.
+   * Receiver MUST validate signature against the RAW HTTP body BEFORE
+   * parsing JSON — common foot-gun if validation happens post-parse
+   * (key ordering / whitespace drift breaks the hash).
+   */
+  hmac_secret?: string;
+}
+
+/** Thrown when an HTTP request fails (network error, timeout, 4xx/5xx, or local validation). */
+export class DeliveryFailedError extends Error {
+  constructor(
+    public readonly agent_id: string,
+    public readonly cause_kind: "network" | "timeout" | "http_status" | "malformed_response" | "client_validation",
+    public readonly http_status: number | null,
+    message: string,
+  ) {
+    super(message);
+    this.name = "DeliveryFailedError";
+  }
+}
+
+export class HttpWebhookAgentConnector implements AgentConnector {
+  static staticCapabilities(): StaticCapabilities {
+    return {
+      connector_type: "agent_connector",
+      implementation: "HttpWebhookAgentConnector",
+      contract_version: "1.0.0",
+      features: { deliver: true, wake: true, list_agents: true, health_check: true },
+    };
+  }
+
+  private readonly agents: Record<string, HttpWebhookAgentConfig>;
+  private readonly timeout_ms: number;
+  private readonly authorization?: string;
+  private readonly hmac_secret?: string;
+
+  constructor(opts: HttpWebhookAgentConnectorOptions) {
+    this.agents = opts.agents;
+    this.timeout_ms = opts.timeout_ms ?? 5000;
+    this.authorization = opts.authorization;
+    this.hmac_secret = opts.hmac_secret;
+  }
+
+  /**
+   * Convenience: build from process.env (looks up the bundled env-var names).
+   *
+   * Validates env-var shape strictly — adopter footguns (NaN timeout, malformed
+   * agents JSON, missing required fields) surface at construction time, not at
+   * first dispatch failure. The validation pattern below is intentionally
+   * educational: adopter forks should copy it.
+   */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): HttpWebhookAgentConnector {
+    const raw = env["HTTP_WEBHOOK_AGENTS"];
+    if (raw === undefined || raw === "") {
+      throw new Error("HTTP_WEBHOOK_AGENTS env var is required (JSON map of agent_id → config).");
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`HTTP_WEBHOOK_AGENTS must be valid JSON: ${(err as Error).message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("HTTP_WEBHOOK_AGENTS must be a JSON object (map of agent_id → config).");
+    }
+    for (const [agent_id, cfg] of Object.entries(parsed)) {
+      if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg)) {
+        throw new Error(`HTTP_WEBHOOK_AGENTS["${agent_id}"]: must be a config object (got ${typeof cfg}).`);
+      }
+      if (typeof (cfg as HttpWebhookAgentConfig).url !== "string" || (cfg as HttpWebhookAgentConfig).url === "") {
+        throw new Error(`HTTP_WEBHOOK_AGENTS["${agent_id}"]: missing required "url" string field.`);
+      }
+    }
+    const agents = parsed as Record<string, HttpWebhookAgentConfig>;
+
+    const rawTimeout = env["HTTP_WEBHOOK_TIMEOUT_MS"];
+    const timeout_ms = rawTimeout !== undefined ? Number.parseInt(rawTimeout, 10) : 5000;
+    if (Number.isNaN(timeout_ms) || timeout_ms <= 0) {
+      throw new Error(`HTTP_WEBHOOK_TIMEOUT_MS must be a positive integer (got: "${rawTimeout}").`);
+    }
+
+    return new HttpWebhookAgentConnector({
+      agents,
+      timeout_ms,
+      ...(env["HTTP_WEBHOOK_AUTH"] !== undefined && env["HTTP_WEBHOOK_AUTH"] !== "" ? { authorization: env["HTTP_WEBHOOK_AUTH"] } : {}),
+      ...(env["HTTP_WEBHOOK_HMAC_SECRET"] !== undefined && env["HTTP_WEBHOOK_HMAC_SECRET"] !== "" ? { hmac_secret: env["HTTP_WEBHOOK_HMAC_SECRET"] } : {}),
+    });
+  }
+
+  async list_agents(): Promise<AgentDescriptor[]> {
+    // Unconditional return per audit Q5.1 — no network ping on the list path
+    // (runtime dispatch calls this to validate connector ownership; ping-first
+    // would double round-trips on every dispatch).
+    return Object.keys(this.agents).map((agent_id) => ({ agent_id }));
+  }
+
+  async deliver(agent_id: string, payload: DeliveryPayload): Promise<DeliveryReceipt> {
+    const cfg = this.agents[agent_id];
+    if (cfg === undefined) {
+      throw new DeliveryFailedError(
+        agent_id, "client_validation", null,
+        `Agent '${agent_id}' is not configured. Wired agents: ${Object.keys(this.agents).join(", ") || "(none)"}.`,
+      );
+    }
+
+    // Wire body: include agent_id at top-level alongside the canonical
+    // DeliveryPayload shape so Model B (single-URL router receivers) can
+    // dispatch without inspecting URL.
+    const body = JSON.stringify({ agent_id, ...payload });
+
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.authorization !== undefined) {
+      headers["Authorization"] = this.authorization;
+    }
+    if (this.hmac_secret !== undefined) {
+      const { createHmac } = await import("node:crypto");
+      const sig = createHmac("sha256", this.hmac_secret).update(body, "utf8").digest("hex");
+      headers["X-Signature"] = `sha256=${sig}`;
+    }
+
+    let response: globalThis.Response;
+    try {
+      response = await fetch(cfg.url, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(this.timeout_ms),
+      });
+    } catch (err) {
+      const e = err as Error;
+      const kind = e.name === "TimeoutError" || e.name === "AbortError" ? "timeout" : "network";
+      throw new DeliveryFailedError(agent_id, kind, null, `${kind} error: ${e.message}`);
+    }
+
+    if (response.status >= 400) {
+      throw new DeliveryFailedError(
+        agent_id, "http_status", response.status,
+        `HTTP ${response.status} from ${cfg.url}`,
+      );
+    }
+
+    // Receiver returns the canonical DeliveryReceipt shape when it can.
+    // Real-world webhooks (NanoClaw, Discord, Slack) return their own shapes;
+    // we tolerantly accept either by parsing what we can and synthesizing
+    // a canonical receipt.
+    let receiverBody: unknown = {};
+    try {
+      const text = await response.text();
+      if (text.length > 0) receiverBody = JSON.parse(text);
+    } catch {
+      // Malformed JSON from receiver — synthesize a minimal receipt rather
+      // than throw. The HTTP layer reported success; agent-side observability
+      // sees delivered_at populated.
+    }
+    return synthesizeReceipt(receiverBody);
+  }
+
+  async wake(agent_id: string, _opts?: WakeOpts): Promise<WakeReceipt> {
+    const cfg = this.agents[agent_id];
+    if (cfg === undefined) {
+      throw new Error(`wake('${agent_id}'): agent not configured`);
+    }
+    if (cfg.wake_url === undefined) {
+      throw new Error(
+        `wake('${agent_id}'): no wake_url configured for this agent. ` +
+        `Add "wake_url" to the agent's config entry in HTTP_WEBHOOK_AGENTS if your substrate supports wake.`,
+      );
+    }
+    // Adopter-specific wake protocol; bundled example just POSTs to the URL.
+    const response = await fetch(cfg.wake_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ agent_id }),
+      signal: AbortSignal.timeout(this.timeout_ms),
+    });
+    if (response.status >= 400) {
+      throw new Error(`wake('${agent_id}'): HTTP ${response.status}`);
+    }
+    return { woken_at: Date.now() };
+  }
+
+  async health_check(): Promise<boolean> {
+    // Default: ping each configured agent's status_url (if any). If no
+    // status_urls configured, return true (we have no probe surface; trust
+    // the URL config until first deliver() proves otherwise).
+    const probes = Object.values(this.agents).filter((c) => c.status_url !== undefined);
+    if (probes.length === 0) return true;
+    try {
+      const results = await Promise.all(probes.map((c) =>
+        fetch(c.status_url!, { method: "GET", signal: AbortSignal.timeout(this.timeout_ms) }),
+      ));
+      return results.every((r) => r.status >= 200 && r.status < 300);
+    } catch {
+      return false;
+    }
+  }
+
+  async request_response(
+    agent_id: string,
+    _payload: DeliveryPayload,
+    _opts: RequestResponseOpts,
+  ): Promise<AgentResponse> {
+    // v0.10 design choice pending: (a) synchronous hold-connection — sender
+    // keeps HTTP connection open, receiver returns reply in body; (b) async
+    // callback — sender provides callback URL in request, receiver POSTs
+    // reply back. The HTTP impl picks one when v0.10 exchange() ships.
+    throw new Error(
+      `[HttpWebhookAgentConnector] request_response('${agent_id}') — not implemented. ` +
+      `Synchronous request-response shipping with v0.10 exchange() op.`,
+    );
+  }
+}
+
+/**
+ * Translate the receiver's HTTP response body into a canonical DeliveryReceipt.
+ * Receivers may return our exact shape, or substrate-specific shapes (Discord
+ * message JSON, NanoClaw `{status, id}`, Slack ts+channel, etc.). Tolerate
+ * variation; synthesize the canonical fields.
+ *
+ * Adopters with strict substrate shape can replace this function (or write
+ * a wrapper) to enforce. Bundled example is permissive by design.
+ */
+function synthesizeReceipt(body: unknown): DeliveryReceipt {
+  const now = Date.now();
+  if (body === null || typeof body !== "object") {
+    return { delivered_at: now };
+  }
+  const obj = body as Record<string, unknown>;
+  const receipt: DeliveryReceipt = {
+    delivered_at: typeof obj["delivered_at"] === "number" ? (obj["delivered_at"] as number) : now,
+  };
+  // Common substrate response fields that map to delivery_id:
+  //   - NanoClaw: { status, id }
+  //   - Discord: { id, ... }
+  //   - Slack: { ts, channel, ... }
+  const idCandidate = obj["delivery_id"] ?? obj["id"] ?? obj["ts"];
+  if (typeof idCandidate === "string") {
+    receipt.delivery_id = idCandidate;
+  }
+  // Adopter signals "accepted but not pushed":
+  if (obj["delivery_skipped"] === true) {
+    receipt.delivery_skipped = true;
+  }
+  return receipt;
+}

package/examples/connectors/HttpWebhookAgentConnector/README.md

@@ -0,0 +1,266 @@
+# HttpWebhookAgentConnector — example
+
+Worked example of `AgentConnector` against an HTTP-webhook substrate. Copy this directory into your codebase, customize per your substrate, register with skillscript-runtime's `Registry`. This README is written for the agent implementing your adopter's connector — including the human reviewing the PR.
+
+**What this demonstrates**: the locked v1.0 contract surface (Q1-Q12 from the v0.9.6 audit) wired through real HTTP traffic, plus the three deployment models the wire format supports.
+
+---
+
+## Quick start
+
+```typescript
+import { Registry } from "skillscript-runtime";
+import { HttpWebhookAgentConnector } from "./HttpWebhookAgentConnector.js";
+
+const registry = new Registry();
+// Async — bootstrap-throws on health_check() returning false (audit Q6).
+await registry.registerAgentConnector("primary", HttpWebhookAgentConnector.fromEnv());
+```
+
+Author writes skills like:
+
+```
+# Skill: morning-status
+# Status: Approved
+# Output: agent: agent-slack
+m:
+    emit(text="overnight sweep clean")
+default: m
+```
+
+Runs → POSTs to the URL configured for `agent-slack` → receiver lands the message in its substrate (Slack, Discord, NanoClaw, whatever).
+
+---
+
+## Configuration
+
+Three env vars; see `.env.example`.
+
+`HTTP_WEBHOOK_AGENTS` — required. Nested JSON map; keys are `agent_id` strings; values are per-agent config:
+
+```json
+{
+  "agent-slack":    { "url": "http://localhost:3200/webhook/slack",    "wake_url": "http://localhost:3200/wake/slack" },
+  "agent-whatsapp": { "url": "http://localhost:3200/webhook/whatsapp" }
+}
+```
+
+- `url` (required) — POST destination for `deliver()` calls
+- `wake_url` (optional) — POST destination for `wake()` calls; throws if missing + skill calls `wake()`
+- `status_url` (optional) — GET probe for `agent_status?()` + `health_check()`; skipped if missing
+
+`HTTP_WEBHOOK_TIMEOUT_MS` — total request duration (connect + send + receive + parse). Default `5000`.
+
+`HTTP_WEBHOOK_AUTH` — bearer-token value. When set, every POST includes `Authorization: <value>`. Use for substrate endpoints behind a shared secret.
+
+`HTTP_WEBHOOK_HMAC_SECRET` — HMAC-SHA256 signing secret. When set, every POST includes `X-Signature: sha256=<hex>`. See [Auth section](#auth) for the body-signing semantics.
+
+---
+
+## Wire format
+
+### Outbound (skillscript → your receiver)
+
+`POST <configured-URL>` with `Content-Type: application/json`:
+
+```json
+{
+  "agent_id": "agent-slack",
+  "kind": "augment",
+  "content": "the message text",
+  "meta": {
+    "dispatch_id": "uuid-v4",
+    "sent_at": 1700000000000,
+    "origin": {
+      "skill_name": "morning-status",
+      "trigger_kind": "cron"
+    },
+    "event_type": "status-update"
+  }
+}
+```
+
+Field semantics:
+
+- **`agent_id`** (top-level, NOT in canonical DeliveryPayload) — included here so Model B receivers (single URL, body-routed) can dispatch without inspecting URL.
+- **`kind`** — `"augment"` (context-to-absorb) or `"template"` (playbook-to-execute).
+- **`content`** / **`prompt`** — message body. `content` for augment kind; `prompt` for template kind.
+- **`meta`** — runtime-filled envelope (skillscript v1.0 contract Q8).
+  - **`dispatch_id`** — UUID per `notify()` invocation. Receivers use for substrate-retry idempotency. Multi-connector broadcast shares dispatch_id; sequential `notify()` calls produce distinct ids.
+  - **`sent_at`** — sender's emit-clock (unix ms). NOT the substrate's delivered_at.
+  - **`origin.skill_name`** — emitter skill.
+  - **`origin.entry_skill_name`** (optional) — root entry-point skill when distinct from `skill_name` (set during procedural composition).
+  - **`origin.trigger_kind`** — `cron` / `session` / `webhook` / `agent` / `cli` / `dashboard` / `inline`.
+  - **`origin.caller_agent_id`** (optional) — root-trigger agent IF identifiable, else absent.
+  - **`event_type`** (optional) — adopter-defined routing vocabulary.
+  - **`correlation_id`** (optional) — reply-correlation for future v0.10 `exchange()` op.
+
+**Optional fields are ABSENT when not set, never present-as-null.** TypeScript `?` semantics: `JSON.stringify` elides `undefined` keys. Receiver code: `if (meta.event_type)` works; `if (meta.event_type !== null)` is wrong.
+
+### Inbound (your receiver → skillscript)
+
+Return JSON body matching canonical `DeliveryReceipt`:
+
+```json
+{
+  "delivered_at": 1700000000005,
+  "delivery_id": "your-substrate-id-optional",
+  "delivery_skipped": false
+}
+```
+
+**The connector is tolerant about receiver response shapes** — if your substrate returns something different (NanoClaw `{status, id}`, Discord message JSON, Slack `{ts, channel}`), the connector synthesizes a canonical receipt by reading common fields:
+
+- `delivered_at` ← receiver's value, else `Date.now()`
+- `delivery_id` ← `delivery_id` / `id` / `ts` (first match)
+- `delivery_skipped` ← receiver's value if `true`
+
+Adopters with strict substrate shape can replace the `synthesizeReceipt()` helper. Bundled example is permissive.
+
+### HTTP status codes
+
+- **2xx** → parse JSON receipt; return through
+- **4xx** → throw `DeliveryFailedError(kind: "http_status")` — permanent failure
+- **5xx** → throw `DeliveryFailedError(kind: "http_status")` — transient (adopter with retry policy forks around this)
+- **Network error / timeout** → throw `DeliveryFailedError(kind: "network" | "timeout")`
+
+---
+
+## Three deployment models
+
+The wire format supports all three without connector code changes:
+
+### Model A — One URL per agent_id
+
+```json
+{
+  "agent-slack":    { "url": "http://nanoclaw-a:3200/webhook" },
+  "agent-whatsapp": { "url": "http://nanoclaw-b:3201/webhook" }
+}
+```
+
+Each URL is fully self-contained — receiver knows where to route by virtue of which host/port/path it was hit on. Adopter runs multiple receivers OR one receiver with URL-distinguished routing (paths/query params).
+
+### Model B — Single URL, router receiver, agent_id in body
+
+```json
+{
+  "agent-slack":    { "url": "http://receiver:3200/webhook" },
+  "agent-whatsapp": { "url": "http://receiver:3200/webhook" }
+}
+```
+
+Both POSTs go to the SAME URL. Receiver inspects `body.agent_id` and dispatches accordingly. Cleaner when adopter already has a routing layer (e.g., one Slack workspace with channel-as-agent_id).
+
+### Model C — Variable-driven channel selection in the skill
+
+```
+# Skill: contextual-alert
+# Status: Approved
+# Vars: CHANNEL="slack"
+
+m:
+    notify(agent="agent-${CHANNEL}", message="alert")
+default: m
+```
+
+Works on top of Model A or B. The skill picks channel at RUNTIME via `${VAR}` substitution. Caller can override per-invocation: `execute_skill(inputs={CHANNEL: "whatsapp"})`.
+
+---
+
+## Auth
+
+### No auth (default)
+
+Skip both `HTTP_WEBHOOK_AUTH` and `HTTP_WEBHOOK_HMAC_SECRET`. Suitable for substrates behind a network boundary (host-local, container-network, VPN-only).
+
+### Bearer token
+
+```
+HTTP_WEBHOOK_AUTH=Bearer abc123
+```
+
+Connector adds `Authorization: Bearer abc123` to every POST. Receiver validates the header. Suitable for trusted internal endpoints; simple shared-secret pattern.
+
+**Bearer + HMAC are combinable.** When both `HTTP_WEBHOOK_AUTH` and `HTTP_WEBHOOK_HMAC_SECRET` are set, every POST gets both an `Authorization` header AND an `X-Signature` header. Most adopters need only one; combine when you want auth-identity AND body-integrity (e.g., bearer identifies the caller, HMAC proves the body wasn't tampered with downstream of caller).
+
+### HMAC-SHA256 body signing
+
+```
+HTTP_WEBHOOK_HMAC_SECRET=<base64-or-hex-secret>
+```
+
+Connector signs the RAW HTTP body with HMAC-SHA256 and adds `X-Signature: sha256=<hex>` header. Use when body-integrity matters (e.g., when HTTPS terminates somewhere unexpected, or when receiver wants tamper-detection).
+
+**Receiver MUST validate signature against the RAW HTTP body BEFORE parsing JSON.** Common foot-gun: receiver decodes JSON first, then re-encodes for hashing → hash mismatch from key ordering / whitespace drift. The bundled receiver examples demonstrate the correct pattern (Express uses `express.raw()`; Flask uses `request.get_data()`).
+
+### Roll your own (OAuth, mTLS, etc.)
+
+Fork `HttpWebhookAgentConnector.ts` + customize the request-construction path. The contract is `AgentConnector.deliver()` — anything that satisfies it works.
+
+---
+
+## Receiver examples
+
+Two reference snippets in `receiver-example/`:
+
+- **`express.js`** — Node + Express. ~50 LOC including HMAC validation.
+- **`flask.py`** — Python + Flask. ~50 LOC, same shape.
+
+Both demonstrate:
+- Raw-body parsing for HMAC validation
+- Skillscript envelope → substrate routing translation
+- Canonical DeliveryReceipt response shape
+- Clock-skew note for staleness checks
+
+Copy + customize per your substrate. These are reference patterns, not shipped code — there are no tests because this is your code path.
+
+---
+
+## What's deliberately out of scope (fork to add)
+
+- **Retries** — example is fail-fast. Retry semantics are substrate-specific (webhook 5xx ≠ rate-limit 429 ≠ substrate-down). Adopters wanting retries customize `deliver()` directly.
+- **Multi-region failover URLs per agent** — adopter-specific.
+- **OAuth flows / mTLS / SAML** — adopter-specific auth providers.
+- **Streaming deliveries (HTTP/2 push, websockets)** — different substrate class.
+- **Async-callback reply pattern for `request_response()`** — v0.10 design choice (sync hold-connection vs async callback). Today the method throws `NotImplementedError` until v0.10 ships `exchange()`.
+
+---
+
+## Forking discipline
+
+If you fork this example into your codebase:
+- **Don't modify the canonical `DeliveryPayload` / `DeliveryReceipt` shapes** — those are skillscript-runtime contracts. Your customizations go in HOW you serialize / parse, not WHAT.
+- **Keep `agent_id` at top-level in the POST body IF you want Model B receivers downstream of your fork** to route without URL inspection. Model-A-only deployments (URL-distinguished routing) can drop it; the canonical contract doesn't require it.
+- **Preserve the `meta` envelope** — adopters downstream rely on `dispatch_id` / `sent_at` / `origin` / `event_type` / `correlation_id`.
+- **If you change the auth model, document it** in your fork's README. Adopter-agents reading your code need to know what's at stake.
+
+---
+
+## Tests
+
+`tests/HttpWebhookAgentConnector.test.ts` exercises:
+
+- `deliver()` posts the correct body shape (agent_id + kind + content + meta)
+- Both `kind: "augment"` and `kind: "template"` round-trip
+- Receiver returns canonical receipt → parsed cleanly
+- Receiver returns substrate-shaped response → synthesizeReceipt translates
+- Receiver returns `delivery_skipped: true` → honored on the receipt
+- 4xx / 5xx → throws `DeliveryFailedError`
+- Network timeout → throws `DeliveryFailedError`
+- `list_agents()` returns all configured agent_ids
+- Multi-agent_id routes to distinct URLs
+- `health_check()` returns true with no status_urls configured
+- `request_response()` throws NotImplementedError (Q1 v0.10 deferred)
+- HMAC signing produces the correct `X-Signature` header value
+- Bearer auth sets the correct `Authorization` header
+
+Run via `vitest run examples/connectors/HttpWebhookAgentConnector/tests/`.
+
+---
+
+## Cross-references
+
+- [Connector Contract Reference](../../../docs/connector-contract-reference.md) — canonical AgentConnector contract
+- [Adopter Playbook](../../../docs/adopter-playbook.md) — broader adopter context
+- [Language Reference](../../../docs/language-reference.md) — `notify()` op + `# Output: agent:` lifecycle hook syntax

package/examples/connectors/HttpWebhookAgentConnector/receiver-example/express.js

@@ -0,0 +1,72 @@
+// Reference receiver for HttpWebhookAgentConnector — Node + Express.
+// Copy + customize per your substrate. ~30 LOC; readable in 60 seconds.
+//
+// What this demonstrates:
+//   - Accepts POST with JSON body matching the canonical DeliveryPayload shape
+//     (kind + content + meta + agent_id at top-level for routing).
+//   - Translates skillscript envelope → your substrate's routing layer.
+//   - Returns canonical DeliveryReceipt shape (delivered_at + optional delivery_id).
+//
+// HMAC validation note: if you use HTTP_WEBHOOK_HMAC_SECRET on the sender,
+// validate the X-Signature header against the RAW HTTP body BEFORE parsing
+// JSON. The pattern below uses express.raw() to expose req.body as a Buffer.
+
+const express = require("express");
+const crypto = require("crypto");
+const { createHmac } = crypto;
+
+const PORT = parseInt(process.env.PORT ?? "3200", 10);
+const HMAC_SECRET = process.env.HMAC_SECRET; // optional
+
+const app = express();
+app.use(express.raw({ type: "application/json", limit: "1mb" }));
+
+app.post("/webhook/:channel?", (req, res) => {
+  // 1) Validate HMAC signature against raw body (BEFORE parsing).
+  if (HMAC_SECRET !== undefined) {
+    const expected = `sha256=${createHmac("sha256", HMAC_SECRET).update(req.body).digest("hex")}`;
+    if (req.headers["x-signature"] !== expected) {
+      return res.status(401).json({ error: "invalid signature" });
+    }
+  }
+
+  // 2) Parse JSON body. Now safe — signature validated against raw bytes.
+  let payload;
+  try {
+    payload = JSON.parse(req.body.toString("utf8"));
+  } catch {
+    return res.status(400).json({ error: "malformed JSON" });
+  }
+
+  // 3) Translate skillscript envelope → your routing layer.
+  // payload.agent_id is the top-level routing key (Model B receivers can
+  // dispatch from this alone). req.params.channel is URL-based routing
+  // (Model A). Use whichever fits your substrate.
+  const text = `[${payload.meta?.origin?.skill_name ?? "skill"}] ${payload.content ?? payload.prompt ?? ""}`;
+  const senderName = `skillscript:${payload.meta?.origin?.skill_name ?? "unknown"}`;
+
+  // your-substrate-here:
+  console.log(`[${req.params.channel ?? payload.agent_id}] ${senderName}: ${text}`);
+  // e.g., NanoClaw-style:
+  //   routeInbound({channelType, platformId, threadId: null,
+  //                  message: { id: payload.meta?.dispatch_id, body: text, sender: senderName }});
+
+  // 4) Return canonical DeliveryReceipt. delivery_id echoes dispatch_id so
+  // sender can correlate. Set delivery_skipped: true if substrate accepts
+  // but won't actually deliver (agent offline, rate-limit, etc.).
+  res.json({
+    delivered_at: Date.now(),
+    delivery_id: payload.meta?.dispatch_id,
+  });
+});
+
+app.get("/health", (_req, res) => res.json({ status: "ok" }));
+
+app.listen(PORT, "0.0.0.0", () => {
+  console.log(`HttpWebhookAgentConnector receiver-example listening on :${PORT}`);
+});
+
+// Clock-skew note: payload.meta.sent_at is the SENDER's emit-clock; your
+// own clock when this request arrives may drift. If you compute staleness
+// as `now - payload.meta.sent_at`, use `Math.max(0, delta)` to avoid
+// negative values when receiver clock runs ahead.