skillscript-runtime 0.9.5 → 0.9.7

package/examples/connectors/HttpWebhookAgentConnector/receiver-example/flask.py

@@ -0,0 +1,77 @@
+"""
+Reference receiver for HttpWebhookAgentConnector — Python + Flask.
+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. Use `request.get_data()` to get the raw bytes; only `request.get_json()`
+after signature validates.
+"""
+import hashlib
+import hmac
+import json
+import os
+import time
+from flask import Flask, request, jsonify
+
+app = Flask(__name__)
+HMAC_SECRET = os.environ.get("HMAC_SECRET")  # optional
+
+
+@app.route("/webhook", methods=["POST"])
+@app.route("/webhook/<channel>", methods=["POST"])
+def webhook(channel=None):
+    raw_body = request.get_data()
+
+    # 1) Validate HMAC signature against raw body (BEFORE parsing).
+    if HMAC_SECRET is not None:
+        expected = "sha256=" + hmac.new(HMAC_SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
+        if request.headers.get("X-Signature") != expected:
+            return jsonify({"error": "invalid signature"}), 401
+
+    # 2) Parse JSON body. Now safe — signature validated against raw bytes.
+    try:
+        payload = json.loads(raw_body.decode("utf-8"))
+    except json.JSONDecodeError:
+        return jsonify({"error": "malformed JSON"}), 400
+
+    # 3) Translate skillscript envelope -> your routing layer.
+    skill_name = payload.get("meta", {}).get("origin", {}).get("skill_name", "skill")
+    content = payload.get("content") or payload.get("prompt", "")
+    text = f"[{skill_name}] {content}"
+    sender_name = f"skillscript:{skill_name}"
+
+    # your-substrate-here:
+    print(f"[{channel or payload.get('agent_id')}] {sender_name}: {text}")
+    # e.g., NanoClaw-style:
+    #   route_inbound(channel_type, platform_id, message={
+    #       "id": payload["meta"]["dispatch_id"], "body": text, "sender": sender_name})
+
+    # 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.).
+    return jsonify({
+        "delivered_at": int(time.time() * 1000),
+        "delivery_id": payload.get("meta", {}).get("dispatch_id"),
+    })
+
+
+@app.route("/health", methods=["GET"])
+def health():
+    return jsonify({"status": "ok"})
+
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", "3200"))
+    app.run(host="0.0.0.0", port=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 `max(0, delta)` to avoid
+# negative values when receiver clock runs ahead.

package/examples/connectors/HttpWebhookAgentConnector/tests/HttpWebhookAgentConnector.test.ts

@@ -0,0 +1,378 @@
+/**
+ * Tests for the HttpWebhookAgentConnector example.
+ *
+ * Uses Node's built-in `http.createServer` as a mock receiver — no
+ * external dependencies. Each test spins up a fresh server bound to
+ * port 0 (kernel-assigned) so tests can run in parallel.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
+import { AddressInfo } from "node:net";
+import { HttpWebhookAgentConnector, DeliveryFailedError } from "../HttpWebhookAgentConnector.js";
+import type { DeliveryPayload } from "../../../../src/connectors/agent.js";
+
+interface RecordedRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string | string[] | undefined>;
+  body: Buffer;
+}
+
+interface MockServer {
+  server: Server;
+  url: string;
+  port: number;
+  received: RecordedRequest[];
+  setResponse: (status: number, body: object | string) => void;
+  close: () => Promise<void>;
+}
+
+async function startMock(): Promise<MockServer> {
+  let responseStatus = 200;
+  let responseBody: object | string = { delivered_at: 1700000000000 };
+  const received: RecordedRequest[] = [];
+
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c) => chunks.push(c as Buffer));
+    req.on("end", () => {
+      received.push({
+        method: req.method ?? "",
+        url: req.url ?? "",
+        headers: req.headers,
+        body: Buffer.concat(chunks),
+      });
+      res.statusCode = responseStatus;
+      res.setHeader("content-type", "application/json");
+      res.end(typeof responseBody === "string" ? responseBody : JSON.stringify(responseBody));
+    });
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = (server.address() as AddressInfo).port;
+  return {
+    server,
+    url: `http://127.0.0.1:${port}`,
+    port,
+    received,
+    setResponse: (status, body) => { responseStatus = status; responseBody = body; },
+    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}
+
+const META_FIXTURE: DeliveryPayload["meta"] = {
+  dispatch_id: "test-dispatch-id",
+  sent_at: 1700000000000,
+  origin: { skill_name: "test-skill", trigger_kind: "inline" },
+};
+
+describe("HttpWebhookAgentConnector — deliver()", () => {
+  let mock: MockServer;
+  beforeEach(async () => { mock = await startMock(); });
+  afterEach(async () => { await mock.close(); });
+
+  it("POSTs canonical envelope with agent_id at top-level", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url } },
+    });
+    await conn.deliver("agent-x", { kind: "augment", content: "hello", meta: META_FIXTURE });
+
+    expect(mock.received).toHaveLength(1);
+    const body = JSON.parse(mock.received[0]!.body.toString("utf8"));
+    expect(body.agent_id).toBe("agent-x");
+    expect(body.kind).toBe("augment");
+    expect(body.content).toBe("hello");
+    expect(body.meta.dispatch_id).toBe("test-dispatch-id");
+    expect(body.meta.origin.skill_name).toBe("test-skill");
+  });
+
+  it("POSTs template kind round-trips", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await conn.deliver("agent-x", { kind: "template", prompt: "playbook body", meta: META_FIXTURE });
+    const body = JSON.parse(mock.received[0]!.body.toString("utf8"));
+    expect(body.kind).toBe("template");
+    expect(body.prompt).toBe("playbook body");
+  });
+
+  it("sends Content-Type: application/json", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(mock.received[0]!.headers["content-type"]).toBe("application/json");
+  });
+
+  it("parses canonical receipt response", async () => {
+    mock.setResponse(200, { delivered_at: 1700000000999, delivery_id: "receiver-id-42", delivery_skipped: false });
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const receipt = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(receipt.delivered_at).toBe(1700000000999);
+    expect(receipt.delivery_id).toBe("receiver-id-42");
+  });
+
+  it("synthesizes receipt from substrate-shaped response (NanoClaw-style { status, id })", async () => {
+    mock.setResponse(202, { status: "accepted", id: "wh-1234-abc" });
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const receipt = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(typeof receipt.delivered_at).toBe("number");
+    expect(receipt.delivery_id).toBe("wh-1234-abc");
+  });
+
+  it("honors delivery_skipped: true from receiver", async () => {
+    mock.setResponse(200, { delivered_at: 1700000000999, delivery_skipped: true });
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const receipt = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(receipt.delivery_skipped).toBe(true);
+  });
+
+  it("synthesizes minimal receipt from empty body (no fields available)", async () => {
+    mock.setResponse(200, "");
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const receipt = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(typeof receipt.delivered_at).toBe("number");
+    expect(receipt.delivery_id).toBeUndefined();
+  });
+
+  it("throws DeliveryFailedError on 4xx", async () => {
+    mock.setResponse(400, { error: "bad request" });
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await expect(
+      conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE }),
+    ).rejects.toThrow(DeliveryFailedError);
+  });
+
+  it("throws DeliveryFailedError on 5xx", async () => {
+    mock.setResponse(503, { error: "service unavailable" });
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const err = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeliveryFailedError);
+    expect((err as DeliveryFailedError).http_status).toBe(503);
+  });
+
+  it("throws DeliveryFailedError when agent_id is not configured", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await expect(
+      conn.deliver("not-wired", { kind: "augment", content: "hi", meta: META_FIXTURE }),
+    ).rejects.toThrow(/not configured/);
+  });
+});
+
+describe("HttpWebhookAgentConnector — Model A + Model B routing", () => {
+  it("Model A: multi-agent_id with distinct URLs → POSTs to the matching URL", async () => {
+    const mockA = await startMock();
+    const mockB = await startMock();
+    try {
+      const conn = new HttpWebhookAgentConnector({
+        agents: {
+          "agent-slack": { url: mockA.url },
+          "agent-whatsapp": { url: mockB.url },
+        },
+      });
+      await conn.deliver("agent-slack", { kind: "augment", content: "via slack", meta: META_FIXTURE });
+      await conn.deliver("agent-whatsapp", { kind: "augment", content: "via whatsapp", meta: META_FIXTURE });
+
+      expect(mockA.received).toHaveLength(1);
+      expect(mockB.received).toHaveLength(1);
+      const bodyA = JSON.parse(mockA.received[0]!.body.toString("utf8"));
+      const bodyB = JSON.parse(mockB.received[0]!.body.toString("utf8"));
+      expect(bodyA.content).toBe("via slack");
+      expect(bodyB.content).toBe("via whatsapp");
+    } finally {
+      await mockA.close();
+      await mockB.close();
+    }
+  });
+
+  it("Model B: multi-agent_id with same URL → agent_id in body distinguishes", async () => {
+    const mock = await startMock();
+    try {
+      const conn = new HttpWebhookAgentConnector({
+        agents: {
+          "agent-slack": { url: mock.url },
+          "agent-whatsapp": { url: mock.url },
+        },
+      });
+      await conn.deliver("agent-slack", { kind: "augment", content: "x", meta: META_FIXTURE });
+      await conn.deliver("agent-whatsapp", { kind: "augment", content: "y", meta: META_FIXTURE });
+
+      expect(mock.received).toHaveLength(2);
+      const ids = mock.received.map((r) => JSON.parse(r.body.toString("utf8")).agent_id);
+      expect(ids).toEqual(["agent-slack", "agent-whatsapp"]);
+    } finally {
+      await mock.close();
+    }
+  });
+});
+
+describe("HttpWebhookAgentConnector — auth", () => {
+  let mock: MockServer;
+  beforeEach(async () => { mock = await startMock(); });
+  afterEach(async () => { await mock.close(); });
+
+  it("bearer-token sets Authorization header", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url } },
+      authorization: "Bearer abc123",
+    });
+    await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(mock.received[0]!.headers["authorization"]).toBe("Bearer abc123");
+  });
+
+  it("bearer + HMAC combinable — both headers set when both options provided", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url } },
+      authorization: "Bearer combined-test",
+      hmac_secret: "combined-secret",
+    });
+    await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(mock.received[0]!.headers["authorization"]).toBe("Bearer combined-test");
+    expect(typeof mock.received[0]!.headers["x-signature"]).toBe("string");
+  });
+
+  it("HMAC signing sets X-Signature header with correct value", async () => {
+    const secret = "test-secret-key";
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url } },
+      hmac_secret: secret,
+    });
+    await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+
+    const rawBody = mock.received[0]!.body.toString("utf8");
+    const { createHmac } = await import("node:crypto");
+    const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+    expect(mock.received[0]!.headers["x-signature"]).toBe(expected);
+  });
+
+  it("no auth headers set when neither auth_header nor hmac_secret configured", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(mock.received[0]!.headers["authorization"]).toBeUndefined();
+    expect(mock.received[0]!.headers["x-signature"]).toBeUndefined();
+  });
+});
+
+describe("HttpWebhookAgentConnector — list_agents / health_check / wake / request_response", () => {
+  let mock: MockServer;
+  beforeEach(async () => { mock = await startMock(); });
+  afterEach(async () => { await mock.close(); });
+
+  it("list_agents returns all configured agent_ids", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: {
+        "agent-slack": { url: mock.url },
+        "agent-whatsapp": { url: mock.url },
+      },
+    });
+    const agents = await conn.list_agents();
+    expect(agents.map((a) => a.agent_id).sort()).toEqual(["agent-slack", "agent-whatsapp"]);
+  });
+
+  it("health_check returns true when no status_urls configured", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    expect(await conn.health_check()).toBe(true);
+  });
+
+  it("health_check pings status_urls when configured + returns true on 2xx", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url, status_url: `${mock.url}/status` } },
+    });
+    mock.setResponse(200, { status: "ok" });
+    expect(await conn.health_check()).toBe(true);
+  });
+
+  it("wake throws when wake_url not configured for the agent", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await expect(conn.wake("agent-x")).rejects.toThrow(/no wake_url configured/);
+  });
+
+  it("wake POSTs to wake_url when configured", async () => {
+    const conn = new HttpWebhookAgentConnector({
+      agents: { "agent-x": { url: mock.url, wake_url: `${mock.url}/wake` } },
+    });
+    const receipt = await conn.wake("agent-x");
+    expect(typeof receipt.woken_at).toBe("number");
+    expect(mock.received).toHaveLength(1);
+    expect(mock.received[0]!.url).toBe("/wake");
+  });
+
+  it("request_response throws NotImplementedError (v0.10 deferred)", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    await expect(
+      conn.request_response("agent-x", { kind: "augment", content: "ping", meta: META_FIXTURE }, { timeout_ms: 1000 }),
+    ).rejects.toThrow(/not implemented/i);
+  });
+});
+
+describe("HttpWebhookAgentConnector — fromEnv()", () => {
+  it("constructs from process.env-shaped object", () => {
+    const env = {
+      HTTP_WEBHOOK_AGENTS: JSON.stringify({ "agent-x": { url: "http://example.com" } }),
+      HTTP_WEBHOOK_TIMEOUT_MS: "8000",
+      HTTP_WEBHOOK_AUTH: "Bearer xyz",
+    };
+    const conn = HttpWebhookAgentConnector.fromEnv(env as NodeJS.ProcessEnv);
+    expect(conn).toBeInstanceOf(HttpWebhookAgentConnector);
+  });
+
+  it("throws when HTTP_WEBHOOK_AGENTS missing", () => {
+    expect(() => HttpWebhookAgentConnector.fromEnv({} as NodeJS.ProcessEnv)).toThrow(/required/);
+  });
+
+  it("throws when HTTP_WEBHOOK_AGENTS is invalid JSON", () => {
+    expect(() => HttpWebhookAgentConnector.fromEnv({ HTTP_WEBHOOK_AGENTS: "not-json" } as NodeJS.ProcessEnv)).toThrow(/valid JSON/);
+  });
+
+  it("throws when HTTP_WEBHOOK_AGENTS parses to non-object (string)", () => {
+    expect(() => HttpWebhookAgentConnector.fromEnv({ HTTP_WEBHOOK_AGENTS: JSON.stringify("just-a-string") } as NodeJS.ProcessEnv))
+      .toThrow(/must be a JSON object/);
+  });
+
+  it("throws when HTTP_WEBHOOK_AGENTS parses to array", () => {
+    expect(() => HttpWebhookAgentConnector.fromEnv({ HTTP_WEBHOOK_AGENTS: JSON.stringify(["a", "b"]) } as NodeJS.ProcessEnv))
+      .toThrow(/must be a JSON object/);
+  });
+
+  it("throws when an agent config is missing url", () => {
+    const env = { HTTP_WEBHOOK_AGENTS: JSON.stringify({ "agent-x": { wake_url: "http://example.com" } }) };
+    expect(() => HttpWebhookAgentConnector.fromEnv(env as NodeJS.ProcessEnv))
+      .toThrow(/missing required "url"/);
+  });
+
+  it("throws when HTTP_WEBHOOK_TIMEOUT_MS is non-numeric (NaN guard)", () => {
+    const env = {
+      HTTP_WEBHOOK_AGENTS: JSON.stringify({ "agent-x": { url: "http://example.com" } }),
+      HTTP_WEBHOOK_TIMEOUT_MS: "abc",
+    };
+    expect(() => HttpWebhookAgentConnector.fromEnv(env as NodeJS.ProcessEnv))
+      .toThrow(/positive integer/);
+  });
+
+  it("throws when HTTP_WEBHOOK_TIMEOUT_MS is zero or negative", () => {
+    const env = {
+      HTTP_WEBHOOK_AGENTS: JSON.stringify({ "agent-x": { url: "http://example.com" } }),
+      HTTP_WEBHOOK_TIMEOUT_MS: "0",
+    };
+    expect(() => HttpWebhookAgentConnector.fromEnv(env as NodeJS.ProcessEnv))
+      .toThrow(/positive integer/);
+  });
+});
+
+describe("HttpWebhookAgentConnector — defensive paths", () => {
+  let mock: MockServer;
+  beforeEach(async () => { mock = await startMock(); });
+  afterEach(async () => { await mock.close(); });
+
+  it("synthesizes minimal receipt when receiver returns malformed JSON", async () => {
+    mock.setResponse(200, "{not-valid-json");
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const receipt = await conn.deliver("agent-x", { kind: "augment", content: "hi", meta: META_FIXTURE });
+    expect(typeof receipt.delivered_at).toBe("number");
+    expect(receipt.delivery_id).toBeUndefined();
+  });
+
+  it("unconfigured agent throws DeliveryFailedError with cause_kind=client_validation", async () => {
+    const conn = new HttpWebhookAgentConnector({ agents: { "agent-x": { url: mock.url } } });
+    const err = await conn.deliver("not-wired", { kind: "augment", content: "hi", meta: META_FIXTURE }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DeliveryFailedError);
+    expect((err as DeliveryFailedError).cause_kind).toBe("client_validation");
+    expect((err as DeliveryFailedError).http_status).toBeNull();
+  });
+});

package/examples/hello.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-27T18:15:17.746Z",
+  "compiled_at": "2026-05-27T23:47:30.644Z",
   "source_skill": {
     "name": "hello"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",