skillscript-runtime 0.18.2 → 0.18.3

package/docs/adopter-playbook.md

@@ -230,6 +230,114 @@ SKILLSCRIPT_HOME=/path/to/adopter skillfile dashboard --config /path/to/adopter/
 
 Each instance reads its own config; ports/paths/db files don't collide.
 
+## Wiring the AgentConnector
+
+`AgentConnector` is the substrate-neutral delivery surface for `# Output: agent: X` / `# Output: template: X` lifecycle hooks and `notify()` / `exchange()` ops. The runtime calls into the contract; your impl decides where the payload lands (webhook, tmux session, file drop, IPC pipe, Slack thread, your own agent harness, etc.).
+
+The full contract surface — methods, payload shapes, receipt shapes, the `agent@session` targeting convention, the graceful-degradation rule — lives in [Connector Contract Reference](connector-contract-reference.md) §AgentConnector. This section covers the **wiring path** for adopters: how to bring an impl online so the runtime uses it.
+
+### Two wiring paths
+
+Same shape as the other substrate slots — programmatic (recommended for custom impls today) or declarative (`connectors.json`, restricted to bundled types).
+
+**(a) Programmatic — for adopter-written impls.** Construct the connector in your bootstrap and pass it via `BootstrapOpts.agentConnector`:
+
+```typescript
+import { bootstrap } from "skillscript-runtime";
+import { MyAgentConnector } from "./my-agent-connector.js";
+
+const { registry, scheduler, server } = await bootstrap({
+  agentConnector: new MyAgentConnector({
+    endpoint: process.env["MY_AGENT_ENDPOINT"],
+    api_key: process.env["MY_AGENT_API_KEY"],
+  }),
+});
+```
+
+`bootstrap()` calls `registry.registerAgentConnector("primary", ...)` for you. `health_check()` fires during registration — wiring failures throw at boot, not at first delivery.
+
+**(b) Declarative `connectors.json`** — for bundled types and the (deferred) custom-via-dynamic-import path:
+
+```json
+{
+  "substrate": {
+    "agent_connector": "noop"
+  }
+}
+```
+
+Bundled short-form values:
+
+| Value | Behavior |
+|---|---|
+| `null` (or omitted) | `NoOpAgentConnector` — silent fallback. `deliver()` / `wake()` log + resolve; `# Output: agent:` declarations complete with a stderr warning. Lets a runtime start with no harness wired. |
+| `"noop"` | Same as `null` but explicitly stated. |
+| Object with `"type": "custom"` | Adopter impl resolved by dynamic-import (deferred — surfaces a clear error today; use programmatic path). |
+
+For full configuration shape, see [Configuration](configuration.md) §"The substrate section."
+
+### Precedence
+
+Same as other substrate slots:
+
+1. **Programmatic** `BootstrapOpts.agentConnector` — explicit, highest priority.
+2. **Declarative** `connectors.json` `substrate.agent_connector` — deployment-durable.
+3. **Built-in default** — `NoOpAgentConnector`. Skills with `# Output: agent:` fire warnings, not errors.
+
+The NoOp fallback is the design choice that makes "runtime works out of box without any AgentConnector wiring" hold. Adopters who want strictness should explicitly wire their connector and let `health_check()` throw if it can't start.
+
+### Worked example
+
+The canonical bundled example is `examples/connectors/HttpWebhookAgentConnector/` — a complete `AgentConnector` impl against an HTTP-webhook substrate. It demonstrates:
+
+- Per-agent URL routing (`HTTP_WEBHOOK_AGENTS` JSON env)
+- Optional `wake_url` per agent — present means wake-capable, absent means degrade-on-wake
+- Bearer + HMAC auth (combinable)
+- Tolerant receipt synthesis (substrate returns substrate-shaped JSON; connector translates to canonical `DeliveryReceipt`)
+- Tests covering the deliver / wake / health-check / request-response surface
+
+Three patterns to copy when forking it for your substrate:
+
+**Pattern 1 — `agent@session` opaque composite.** Every messaging substrate needs either bare-identity OR specific-live-session addressing. The contract keeps `agent_id` opaque; sessions ride as `"perry@kitchen-terminal"` or via `WakeOpts.session_id`. Substrates that care decompose; substrates that don't ignore. Pick one form for your fork and document it in your impl's README:
+
+```typescript
+async wake(agent_id: string, opts?: WakeOpts): Promise<WakeReceipt> {
+  // Form A — composite in agent_id
+  const [agent, embeddedSession] = agent_id.split("@");
+  // Form B — opts.session_id wins if both supplied
+  const session = opts?.session_id ?? embeddedSession;
+  // ... route to (agent, session)
+  return { woken_at: Date.now(), woken: true, ...(session ? { session_id: session } : {}) };
+}
+```
+
+**Pattern 2 — graceful degradation on wake.** `wake()` must not throw because your substrate lacks interrupt capability. Distinguish capability-gap (degrade) from operational-fault (throw):
+
+```typescript
+async wake(agent_id: string, _opts?: WakeOpts): Promise<WakeReceipt> {
+  const cfg = this.agents[agent_id];
+  if (!cfg) throw new Error(`agent not configured: ${agent_id}`);  // operational fault
+  if (!cfg.wake_url) {
+    // capability gap — no interrupt channel for this agent — degrade
+    return { woken_at: Date.now(), woken: false };
+  }
+  const response = await fetch(cfg.wake_url, { ... });
+  if (!response.ok) throw new DeliveryFailedError(...);  // operational fault
+  return { woken_at: Date.now(), woken: true };
+}
+```
+
+Callers reading `WakeReceipt.woken` distinguish "the substrate woke them" from "the substrate stored the payload for later" without needing per-substrate knowledge.
+
+**Pattern 3 — session echo on receipts.** When your substrate routes to a specific session, echo it back on `DeliveryReceipt.session_id` / `WakeReceipt.session_id`. Dashboards rendering "delivered to perry@kitchen-terminal" rather than just "delivered to perry" depend on this.
+
+### When to fork vs. when to write fresh
+
+- **Fork `HttpWebhookAgentConnector`** when your substrate is HTTP-shaped and your changes are: tweaked auth (OAuth, mTLS), retry policy, different routing model. Most production deployments end up here.
+- **Write fresh** when your substrate is fundamentally non-HTTP (tmux, file drop, gRPC, websocket-push). Implement the five required methods (`list_agents`, `deliver`, `wake`, `health_check`, `request_response`) + optional `agent_status`. Use `NoOpAgentConnector` as the minimal-shape reference.
+
+In either case: write tests against the contract methods (the bundled example's `tests/HttpWebhookAgentConnector.test.ts` is a useful template), wire via `BootstrapOpts.agentConnector`, and let `health_check()` enforce the "fail-at-boot, not at first delivery" property.
+
 ## Authoring posture — who owns the skills you write
 
 Every skill stored in a `SkillStore` carries a `SkillMeta.author` field captured at first-write. The author is then load-bearing at dispatch time: the runtime threads it into `ctx.agentId` so identity-scoped substrates (memory stores, multi-tenant DBs) read and write under that scope.

package/docs/configuration.md

@@ -4,7 +4,7 @@ How to configure a skillscript-runtime deployment.
 
 The single config file is **`~/.skillscript/connectors.json`** (or any path passed via `--connectors`). It has two top-level concerns:
 
-1. **`substrate`** — which `SkillStore`, `DataStore`, and `LocalModel` the runtime hosts (MCP server + web dashboard) use.
+1. **`substrate`** — which `SkillStore`, `DataStore`, `LocalModel`, and `AgentConnector` the runtime hosts (MCP server + web dashboard) use.
 2. **Named MCP connector instances** — `youtrack`, `github`, etc. — invoked via `$ <name>` in skill source.
 
 The runtime loads `connectors.json` at startup. Missing file → graceful empty config (substrate defaults to filesystem skills + conditional sqlite memories; no MCP connectors). Malformed JSON or unknown fields → structured errors surfaced at bootstrap.
@@ -123,12 +123,13 @@ A typical out-of-the-box `~/.skillscript/connectors.json`:
   "substrate": {
     "skill_store": "filesystem",
     "data_store": "sqlite",
-    "local_model": null
+    "local_model": null,
+    "agent_connector": null
   }
 }
 ```
 
-Equivalent to omitting the file entirely — these are the base config defaults.
+Equivalent to omitting the file entirely — these are the base config defaults. `agent_connector: null` falls back to the silent `NoOpAgentConnector` — skills with `# Output: agent: X` complete cleanly with a stderr warning; replace with `"noop"` for the same behavior stated explicitly, or with a `"custom"` entry to wire an adopter impl.
 
 To switch skills storage to SQLite:
 
@@ -165,14 +166,16 @@ Valid short-form values per slot:
 | `skill_store` | `"filesystem"` \| `"sqlite"` |
 | `data_store` | `"sqlite"` |
 | `local_model` | (none — `"ollama"` requires the object form with `defaultModelTag`; see below) |
+| `agent_connector` | `"noop"` (explicit silent fallback; same behavior as `null`) |
 
 ### Null — explicit "no substrate"
 
 ```json
-"local_model": null
+"local_model": null,
+"agent_connector": null
 ```
 
-The runtime doesn't register a connector for this slot. Useful for explicitly disabling LocalModel when nothing local is available.
+The runtime doesn't register a real connector for this slot. `local_model: null` leaves `$ llm` un-wired (skills calling it error at execute time). `agent_connector: null` falls back to `NoOpAgentConnector` — `# Output: agent:` declarations complete with a stderr warning instead of throwing, so a runtime can start without any agent harness wired.
 
 ### Object form — override defaults
 
@@ -193,6 +196,7 @@ The runtime doesn't register a connector for this slot. Useful for explicitly di
 | `sqlite` (skill_store) | `dbPath` (default: `$SKILLSCRIPT_HOME/skills/skills.db`) |
 | `sqlite` (data_store) | `dbPath` (default: `$SKILLSCRIPT_HOME/data.db`; `DATA_DB` env overrides) |
 | `ollama` (local_model) | `baseUrl` (default: `OLLAMA_BASE_URL` env or `http://localhost:11434`), **`defaultModelTag` (required — e.g., `"gemma2:9b"`, `"llama3.1:8b"`)** |
+| `noop` (agent_connector) | none — silent fallback (warn + resolve). Real adopter impls use the `custom` form below. |
 
 > **`SqliteDataStore` feature surface.** The bundled `sqlite` data_store is a deliberately minimal reference implementation: `supports_writes` + `supports_tag_filter` are true; `supports_semantic`, `supports_pinning`, `supports_decay_model`, `supports_thread_status_filter` are all false. Rich features (semantic retrieval, pinning, decay scoring, thread-status workflow) come from substrate impls — adopters fork `examples/connectors/DataStoreTemplate/` and wire their backing system (memory broker, vector DB, AMP, etc.). The bundled impl exists so the runtime works out-of-box; adopters with richer query semantics write their own.
 
@@ -218,17 +222,28 @@ Pin the model tag explicitly — must be a tag your Ollama instance has pulled (
 ```json
 "skill_store": {
   "type": "custom",
-  "module": "./my-amp-skill-store.js",
-  "export": "AmpSkillStore",
+  "module": "./my-skill-store.js",
+  "export": "MySkillStore",
   "config": {
     "vault": "team"
   }
 }
 ```
 
-References an adopter-written class implementing the relevant contract. `module` is the path to the JS file; `export` is the named export (defaults to `default`); `config` is passed to the constructor.
+References an adopter-written class implementing the relevant contract. `module` is the path to the JS file; `export` is the named export (defaults to `default`); `config` is passed to the constructor. The same shape works for any substrate slot:
 
-> **Limitation**: sync `bootstrap()` can't dynamic-import. Custom-via-connectors.json surfaces a clear error and falls back to the default. Adopters wanting custom impls today write a programmatic bootstrap that calls `registry.registerSkillStore("primary", new AmpSkillStore(...))` directly — same pattern as the runtime's reference `bootstrap()`. Async-bootstrap with dynamic-import support is planned.
+```json
+"agent_connector": {
+  "type": "custom",
+  "module": "./my-agent-connector.js",
+  "export": "MyHttpWebhookAgentConnector",
+  "config": {
+    "endpoint": "${AGENT_ENDPOINT}"
+  }
+}
+```
+
+> **Limitation**: sync `bootstrap()` can't dynamic-import. Custom-via-connectors.json surfaces a clear error and falls back to the default. Adopters wanting custom impls today write a programmatic bootstrap that calls `registry.registerSkillStore("primary", new MySkillStore(...))` (or `registry.registerAgentConnector(...)`) directly — same pattern as the runtime's reference `bootstrap()`. Async-bootstrap with dynamic-import support is planned.
 
 ---
 
@@ -236,9 +251,9 @@ References an adopter-written class implementing the relevant contract. `module`
 
 When multiple config sources speak:
 
-1. **Programmatic opts** (`opts.skillStore` passed to `bootstrap()`) — explicit, highest priority
+1. **Programmatic opts** (`opts.skillStore` / `opts.dataStore` / `opts.localModel` / `opts.agentConnector` passed to `bootstrap()`) — explicit, highest priority
 2. **`connectors.json` substrate section** — declarative, deployment-durable
-3. **Built-in default** — fallback (filesystem skill_store; conditional sqlite data_store; no local_model)
+3. **Built-in default** — fallback (filesystem skill_store; conditional sqlite data_store; no local_model; NoOpAgentConnector)
 
 If two configs disagree, the higher-priority one wins; lower-priority is ignored without error.
 

package/docs/connector-contract-reference.md

@@ -1,6 +1,6 @@
 # Connector Contract Reference
 
-The substrate-neutral contracts skillscript-runtime exposes for adopters to wire their own substrate behind. This doc is the **canonical source of truth** for the AgentConnector contract as locked at v1.0 by the v0.9.6 audit (Perry's thread `b722bbf4`).
+The substrate-neutral contracts skillscript-runtime exposes for adopters to wire their own substrate behind. This doc is the **canonical source of truth** for the AgentConnector contract. The interface shape was locked at v1.0 by the v0.9.6 audit (thread `b722bbf4`); the wake/deliver receipt shapes carry post-lock refinements per the v0.18.2 session-targeting + graceful-degradation requirements.
 
 **Audience**: this doc is written for the agent that's implementing an adopter's AgentConnector — typically an LLM-class agent supervised by a human. If you're a human reading it directly, the same content applies; the prose is tightened for agent comprehension (literal field semantics, explicit precedence rules, worked examples).
 
@@ -8,7 +8,7 @@ Other contracts (McpConnector, SkillStore, DataStore, LocalModel) audit + lock i
 
 ---
 
-## AgentConnector — v1.0 contract (locked v0.9.6)
+## AgentConnector — v1.0 contract
 
 ### Purpose
 
@@ -81,14 +81,78 @@ interface DeliveryMeta {
 interface DeliveryReceipt {
   delivered_at: number;
   delivery_id?: string;
+  session_id?: string;
   delivery_skipped?: boolean;
 }
 ```
 
 - **`delivered_at`**: substrate-acknowledgement timestamp. When the substrate confirmed it accepted the delivery.
 - **`delivery_id`**: substrate-specific id for callers to correlate later.
+- **`session_id`**: the session that received the delivery. Set when the substrate routes to a specific session (e.g., per-terminal mailbox, per-tab webhook). Omitted when the substrate is agent-level only (Slack DM, email — no session concept) or when the substrate fans out / accepts without committing to a session. See *agent@session targeting* below.
 - **`delivery_skipped`**: adopter signals "accepted but not pushed to the agent" — offline, rate-limit drop, tmux session exists but agent hasn't read, etc. Distinct from outright failure (which throws). Runtime echoes this on the receipt record for dashboard observability.
 
+### WakeOpts + WakeReceipt
+
+```typescript
+interface WakeOpts {
+  context?: string;
+  when?: "immediate" | number;
+  session_id?: string;
+}
+
+interface WakeReceipt {
+  woken_at: number;
+  woken: boolean;
+  session_id?: string;
+}
+```
+
+- **`WakeOpts.context`**: optional preamble to prepend to the wake message.
+- **`WakeOpts.when`**: `"immediate"` (default) or a unix-ms timestamp for scheduled wake.
+- **`WakeOpts.session_id`**: structured session targeting. Alternative to embedding `agent@session` in the `agent_id` opaque string. Callers with the session already separated (e.g., a dashboard's per-session "wake this terminal" action) pass it here. When both forms are supplied, `opts.session_id` takes precedence over the embedded suffix.
+- **`WakeReceipt.woken_at`**: substrate's acknowledgement timestamp.
+- **`WakeReceipt.woken`** (required): honest signal of whether the substrate actually interrupted the agent. See *Graceful degradation on wake* below — this is the read every caller does to distinguish interrupted-them from delivered-only.
+- **`WakeReceipt.session_id`**: the session that received the wake (or delivery, if degraded). Set when the substrate knows; omit otherwise.
+
+### agent@session targeting
+
+`agent_id` is an opaque string. The substrate may treat it as:
+
+- A bare agent identifier (`alice`, an email address, a Slack `@user`, a Discord user ID).
+- A composite `agent@session` (e.g., `"perry@kitchen-terminal"`) when the substrate tracks multiple live sessions per identity.
+
+The substrate decomposes the composite if it cares; non-session substrates ignore the suffix or treat the whole string as the address. This keeps the contract substrate-neutral while preserving session-granular routing — every messaging substrate either addresses a bare identity OR a specific live session, and the opaque-composite form covers both without locking adopters into a particular session model.
+
+**Two forms, one wire**:
+
+```typescript
+// Form A — composite in agent_id (works for deliver + wake)
+await conn.wake("perry@kitchen-terminal");
+
+// Form B — structured WakeOpts.session_id (wake only)
+await conn.wake("perry", { session_id: "kitchen-terminal" });
+```
+
+Substrates that care about sessions read both — `opts.session_id` wins if both are set. Substrates that don't care ignore both. Callers that already have agent + session as separate variables prefer Form B; callers passing an opaque user-supplied address prefer Form A.
+
+`DeliveryReceipt.session_id` and `WakeReceipt.session_id` echo the resolved session back to the caller. Useful for dashboards rendering "delivered to perry@kitchen-terminal" rather than just "delivered to perry."
+
+### Graceful degradation on wake
+
+Not every substrate can interrupt. A webhook receiver, a file-drop directory, or a store-only adopter has no attention channel — they can persist the payload but can't make the agent look at it now.
+
+**The rule**: `wake()` must not throw because the substrate lacks interrupt capability. Conform by degrading: deliver the payload as if it were a `deliver()` call, set `woken: false` on the receipt. Callers reading the receipt distinguish "the substrate woke the agent" from "the substrate stored the payload for later" without needing per-substrate knowledge.
+
+| Situation | `wake()` behavior | `WakeReceipt.woken` |
+|---|---|---|
+| Substrate has live interrupt channel + agent is reachable | Send interrupt | `true` |
+| Substrate has no interrupt channel (webhook, file-drop) | Deliver content, no interrupt | `false` |
+| Substrate has interrupt channel but agent unreachable / offline | Best-effort deliver, no interrupt | `false` |
+| Caller misconfiguration (unknown `agent_id`, missing required config) | Throw `DeliveryFailedError` | — |
+| Substrate fault (network, auth) | Throw | — |
+
+The distinction `wake-capability` vs `network-fault` matters. The former is structural (this substrate fundamentally can't wake) and degrades silently. The latter is operational (the substrate could wake but something broke) and throws. Adopters writing connectors should keep this distinction explicit — the bundled `HttpWebhookAgentConnector` returns `woken: false` when `wake_url` is unconfigured (capability gap, fixed at config time) but throws on actual HTTP failure (operational fault, surfaces to caller).
+
 ---
 
 ## Use-site cross-reference table
@@ -129,7 +193,7 @@ Implementation checklist:
 
 2. **Implement `deliver(agent_id, payload)`** — serialize `payload` to your substrate's format. For HTTP: JSON body with `kind`, `content`/`prompt`, and `meta`. For tmux: serialize meta as a header line, write content via `tmux send-keys`. For file-drop: write a file under `<dir>/<dispatch_id>.{json,txt}`.
 
-3. **Implement `wake(agent_id, opts?)`** — substrate-specific "rouse the agent." Webhook: POST to a `/wake` endpoint. Tmux: send a wake-up sequence. Etc.
+3. **Implement `wake(agent_id, opts?)`** — substrate-specific "rouse the agent." Wake-capable substrates: send an attention signal (tmux: wake-up sequence; webhook with a `/wake` endpoint: POST it; push channel: send notification). Set `woken: true` on the receipt. Passive substrates (file-drop, store-only, webhook without `/wake`): degrade gracefully — deliver the content, return `woken: false`. NEVER throw because the substrate lacks interrupt capability. Honor `opts.session_id` if your substrate tracks sessions; otherwise ignore it. Echo the resolved session on `WakeReceipt.session_id` so dashboards can render it.
 
 4. **Implement `health_check()`** — return `true` if substrate is reachable + configured. Webhook: HEAD/OPTIONS your endpoint. Tmux: check the session exists. File-drop: check the directory is writable.
 
@@ -203,4 +267,4 @@ The shape-vs-semantics split is deliberate (see [[ARCHITECTURE INVARIANT 88df79c
 
 ---
 
-*This doc reflects the v0.9.6 AgentConnector lock + v0.13.8 storage-conventions addition; future contract changes update this file alongside the code.*
+*This doc reflects the v0.9.6 AgentConnector interface lock, v0.13.8 storage-conventions addition, and v0.18.2 receipt-shape refinements (woken-honesty + session targeting + graceful degradation). Future contract changes update this file alongside the code.*

package/examples/connectors/HttpWebhookAgentConnector/README.md

@@ -46,7 +46,7 @@ Three env vars; see `.env.example`.
 ```
 
 - `url` (required) — POST destination for `deliver()` calls
-- `wake_url` (optional) — POST destination for `wake()` calls; throws if missing + skill calls `wake()`
+- `wake_url` (optional) — POST destination for `wake()` calls. When absent, `wake()` degrades gracefully: returns `WakeReceipt {woken: false}` instead of throwing. Distinguishes capability-gap (this agent has no interrupt channel) from operational fault (HTTP error), per the contract's graceful-degradation rule.
 - `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`.
@@ -105,6 +105,7 @@ Return JSON body matching canonical `DeliveryReceipt`:
 {
   "delivered_at": 1700000000005,
   "delivery_id": "your-substrate-id-optional",
+  "session_id": "kitchen-terminal-optional",
   "delivery_skipped": false
 }
 ```
@@ -113,6 +114,7 @@ Return JSON body matching canonical `DeliveryReceipt`:
 
 - `delivered_at` ← receiver's value, else `Date.now()`
 - `delivery_id` ← `delivery_id` / `id` / `ts` (first match)
+- `session_id` ← receiver's value if present (substrate-routed to a specific session)
 - `delivery_skipped` ← receiver's value if `true`
 
 Adopters with strict substrate shape can replace the `synthesizeReceipt()` helper. Bundled example is permissive.
@@ -124,6 +126,25 @@ Adopters with strict substrate shape can replace the `synthesizeReceipt()` helpe
 - **5xx** → throw `DeliveryFailedError(kind: "http_status")` — transient (adopter with retry policy forks around this)
 - **Network error / timeout** → throw `DeliveryFailedError(kind: "network" | "timeout")`
 
+### Wake — capability gap vs. operational fault
+
+`wake()` distinguishes two failure modes per the contract's graceful-degradation rule:
+
+| Situation | `wake()` behavior | `WakeReceipt.woken` |
+|---|---|---|
+| `wake_url` configured for `agent_id`, POST returns 2xx | Send attention signal | `true` |
+| `wake_url` NOT configured for `agent_id` (capability gap — this substrate has no interrupt channel for this agent) | No-op, return receipt | `false` |
+| `agent_id` not configured at all (caller misconfiguration) | Throw `Error("agent not configured: ...")` | — |
+| `wake_url` configured but POST fails (operational fault) | Throw `DeliveryFailedError` | — |
+
+The capability-gap case (no `wake_url`) is a deliberate fork choice: passive substrates conform by degrading. Callers reading `WakeReceipt.woken` distinguish interrupted-them from delivered-only without needing per-substrate knowledge.
+
+### `agent@session` targeting
+
+`agent_id` is opaque to the connector at the wire level — whatever the skill passes flows through to the configured per-agent `url`. Substrates that track multiple live sessions per identity can address them via the `agent@session` composite (e.g., `"perry@kitchen-terminal"`) OR the structured `WakeOpts.session_id` form. The connector forwards the resolved `agent_id` in the POST body; the receiver decomposes if it cares. Echo the resolved session on `DeliveryReceipt.session_id` / `WakeReceipt.session_id` so dashboards can render "delivered to perry@kitchen-terminal" instead of just "delivered to perry."
+
+See [Connector Contract Reference](../../../docs/connector-contract-reference.md) §"agent@session targeting" + §"Graceful degradation on wake" for the contract-level rules.
+
 ---
 
 ## Three deployment models
@@ -254,6 +275,8 @@ If you fork this example into your codebase:
 - `request_response()` throws NotImplementedError (Q1 v0.10 deferred)
 - HMAC signing produces the correct `X-Signature` header value
 - Bearer auth sets the correct `Authorization` header
+- `wake()` degrades to `woken: false` when `wake_url` is unconfigured (graceful degradation)
+- `wake()` returns `woken: true` when the POST succeeds
 
 Run via `vitest run examples/connectors/HttpWebhookAgentConnector/tests/`.
 

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-05T20:34:57.556Z",
+  "compiled_at": "2026-06-05T20:35:05.809Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "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>",