skillscript-runtime 0.18.4 → 0.18.5

package/docs/connector-contract-reference.md

@@ -125,6 +125,18 @@ interface WakeReceipt {
 
 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.
 
+**Address-routed dispatch (v0.18.5)**: the runtime uses the presence of `@` in `agent_id` to decide between `deliver()` and `wake()` for skill-author surfaces (`notify()` op + `# Output: agent:` / `# Output: template:` lifecycle hooks):
+
+| Skill-author syntax | Address shape | Connector method called |
+|---|---|---|
+| `notify(agent="perry", …)` | bare | `deliver()` |
+| `notify(agent="perry@kitchen-terminal", …)` | composite | `wake()` |
+| `# Output: agent: perry` | bare | `deliver()` |
+| `# Output: agent: perry@kitchen-terminal` | composite | `wake()` |
+| `# Output: template: perry@browser-tab-3` | composite | `wake()` |
+
+The runtime threads the FULL composite to `wake()` — substrate decomposes per the rule above. For wake-routed dispatches, the skill's content (notify message or accumulated emissions) rides as `WakeOpts.context`. Per Perry's design call (thread `c453afa2`): "the address encodes delivery class" — same rule as the broader `waiting_on` / mailbox / broker convention. No `wake=true` kwarg exists; the `@` IS the signal.
+
 **Two forms, one wire**:
 
 ```typescript
@@ -159,12 +171,17 @@ The distinction `wake-capability` vs `network-fault` matters. The former is stru
 
 ## Use-site cross-reference table
 
-| Language surface | Runtime method | DeliveryPayload kind | meta sourced from |
-|---|---|---|---|
-| `# Output: agent: X` lifecycle hook | `AgentConnector.deliver()` | `augment` | Frontmatter `# Event-type:` (if set); `event_type` & `correlation_id` always undefined |
-| `# Output: template: X` lifecycle hook | `AgentConnector.deliver()` | `template` | Same as above |
-| `notify(agent=X, message=..., event_type=..., correlation_id=...)` op | `AgentConnector.deliver()` | `augment` | Kwargs override frontmatter for `event_type`; `correlation_id` from kwarg only |
-| `exchange(agent=X, message=..., timeout=...)` op (locked-shape, runtime support pending) | `AgentConnector.request_response()` | `augment` | Same as notify; correlation_id required |
+| Language surface | Address shape | Runtime method | DeliveryPayload kind | meta sourced from |
+|---|---|---|---|---|
+| `# Output: agent: X` lifecycle hook | bare | `AgentConnector.deliver()` | `augment` | Frontmatter `# Event-type:` (if set); `event_type` & `correlation_id` always undefined |
+| `# Output: agent: X@session` lifecycle hook | composite | `AgentConnector.wake()` | n/a (joined emissions as `WakeOpts.context`) | n/a (wake has no envelope) |
+| `# Output: template: X` lifecycle hook | bare | `AgentConnector.deliver()` | `template` | Same as agent-bare |
+| `# Output: template: X@session` lifecycle hook | composite | `AgentConnector.wake()` | n/a | n/a |
+| `notify(agent=X, message=..., event_type=..., correlation_id=...)` op | bare | `AgentConnector.deliver()` | `augment` | Kwargs override frontmatter for `event_type`; `correlation_id` from kwarg only |
+| `notify(agent=X@session, message=..., ...)` op | composite | `AgentConnector.wake()` | n/a (message as `WakeOpts.context`) | n/a |
+| `exchange(agent=X, message=..., timeout=...)` op (locked-shape, runtime support pending) | bare | `AgentConnector.request_response()` | `augment` | Same as notify; correlation_id required |
+
+The address-routing rule (v0.18.5) is uniform across all skill-author surfaces: `@session` present → wake-class; bare → deliver-class. See *agent@session targeting* below for the contract-level convention.
 
 ---
 
@@ -269,4 +286,4 @@ The shape-vs-semantics split is deliberate (see [[ARCHITECTURE INVARIANT 88df79c
 
 ---
 
-*This doc reflects the v0.9.6 AgentConnector interface lock, v0.13.8 storage-conventions addition, v0.18.2 receipt-shape refinements (woken-honesty + session targeting + graceful degradation), and v0.18.4 caller-identity-threading + `DeliveryReceipt.warnings`. 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, v0.18.2 receipt-shape refinements (woken-honesty + session targeting + graceful degradation), v0.18.4 caller-identity-threading + `DeliveryReceipt.warnings`, and v0.18.5 address-routed dispatch (skill-author surfaces route deliver vs. wake on `@session` presence) + `WakeReceipt.warnings`. Future contract changes update this file alongside the code.*

package/docs/language-reference.md

@@ -418,17 +418,20 @@ Per-output-kind consumption semantics: presentation surfaces (`# Output: agent:
 ```
 notify(agent="oncall", message="Threshold breached at ${COUNT}")
 notify(agent="ops", message="ticket TR-1234 is a showstopper", event_type="ticket-911", correlation_id="${INCIDENT_ID}")
+notify(agent="cc@kitchen-terminal", message="look here now")
 ```
 
 Synchronous alert to a named agent via wired AgentConnector(s). **Contrast with `emit`:** `emit` accumulates into end-of-skill bulk delivery via the `# Output: agent: <name>` lifecycle hook; `notify` fires mid-execution to interrupt or page an agent before the skill completes.
 
-- `agent` — target agent id (required)
-- `message` — alert body (optional; defaults to accumulated emissions so far)
-- `event_type` — adopter-defined routing label (optional; flows to `DeliveryMeta.event_type`; overrides `# Event-type:` frontmatter)
-- `correlation_id` — reply-correlation id (optional; required for future `exchange()` / `request_response()` paths)
-- `connectors` — JSON array restricting which wired AgentConnector(s) receive the dispatch (optional)
+- `agent` — target agent id (required). **Address-routing**: a bare identifier (`"perry"`) routes to `AgentConnector.deliver()` (mailbox-class — the agent's inbox); an `agent@session` composite (`"cc@kitchen-terminal"`) routes to `AgentConnector.wake()` (session-targeted interrupt). The `@session` suffix IS the wake signal — there's no `wake=true` kwarg. Substrate sees the opaque composite on `wake()` and decomposes per the v0.18.2 contract.
+- `message` — alert body (optional; defaults to accumulated emissions so far). For wake-routed dispatches, the message rides as `WakeOpts.context` (preamble for the interrupt signal).
+- `event_type` — adopter-defined routing label (optional; flows to `DeliveryMeta.event_type` on deliver-class dispatches; ignored on wake-class since wake has no envelope).
+- `correlation_id` — reply-correlation id (optional; required for future `exchange()` / `request_response()` paths).
+- `connectors` — JSON array restricting which wired AgentConnector(s) receive the dispatch (optional).
 
-Returns ACK `{agent, dispatched: [{connector, ok, error?}]}` — fire-and-forget callers ignore the binding; check-delivery callers inspect ACK.
+Returns ACK `{agent, dispatched: [{connector, ok, route?, error?}]}` — `route` is `"deliver"` or `"wake"` per address-routing. Fire-and-forget callers ignore the binding; check-delivery callers inspect ACK.
+
+The same address rule applies to lifecycle hooks: `# Output: agent: perry` routes to deliver; `# Output: agent: cc@kitchen-terminal` routes to wake. See Output targets below.
 
 ### `shell` — sandboxed or unsafe shell exec
 
@@ -1340,20 +1343,26 @@ The Augmenting-kind delivery. Output prepends to the named agent's next-turn pro
 
 ```
 # Output: agent: <agent-name>
+# Output: agent: cc@kitchen-terminal
 ```
 
 Used to bring an agent into the next turn pre-shaped — context that would normally require a session-start retrieval is pre-positioned. Wired end-to-end via the runtime host's prompt-prepend surface + a synchronous trigger-fire endpoint with timeout-fallback so the next-turn dispatch isn't blocked on slow skill execution.
 
+**Address-routing** — same rule as `notify()`. A bare `<agent-name>` routes to `AgentConnector.deliver()` (mailbox-class). An `<agent>@<session>` composite routes to `AgentConnector.wake()` (session-targeted interrupt); the joined emit stream rides as `WakeOpts.context`. The `@session` suffix IS the wake signal — no separate `wake=true` form.
+
 ### `template: <agent-name>` — playbook delivered to a named agent
 
 The Template-kind delivery. Output renders as a playbook the named agent executes itself — the runtime doesn't dispatch the ops, it hands the agent a recipe to follow.
 
 ```
 # Output: template: <agent-name>
+# Output: template: cc@browser-tab-3
 ```
 
 Used for reusable recipes: a skill that, when compiled, produces instructions another agent follows.
 
+**Address-routing**: same as `agent:` above. Bare → deliver(); `@session` → wake().
+
 ### `file: <path>` — write to file
 
 Header parses; file router not yet implemented. See "Not yet implemented, but planned" at top.

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-05T21:29:38.495Z",
+  "compiled_at": "2026-06-05T22:02:26.885Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

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