@sjawhar/claude-envoy 0.0.0 → 1.1.0

package/skills/plain-words/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: plain-words
+description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. It removes empty verb phrases and replaces each with the literal thing. Use it after you write and before you send."
+---
+
+# Say the literal thing
+
+The operator made this a rule: delete the empty verb phrases agents keep using, and say the literal
+thing instead.
+
+Run this over your text before you send it. It takes a minute and it is not optional.
+
+## The test
+
+Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
+happens, you did not know, and the phrase hid it from you as well as from the reader.
+
+## The phrases, in the order agents actually use them
+
+Counted on 2026-10-30, in one day's 198,898 assistant messages across one fleet of agents:
+
+| Never | Used that day | What to write |
+|---|---:|---|
+| land the change, land the PR | **1,053** | merge it, release it, deploy it, apply it — whichever one it is |
+| unblock the work | 151 | X can start once Y merges |
+| name the problem, name the owner, name a date | 23 | say the problem; who owns it is X; it is due on 11-02 |
+| it pays for itself, that pays | 13 | it costs $16,306 and returns $60,379 a month |
+| carry it to X, carry the finding | 11 | tell X; send it to X; put it on the issue |
+| this shows the gap, the number shows | 5 | the gap is 12 of 30; the number is 1.17 |
+
+**The trigger for the commonest one:** you reach for "land" when you cannot say whether it merged,
+released or deployed. If you can say which, say it. If you cannot, that is the sentence — "it is
+approved and not merged" — and it is more useful than any verb.
+
+**"name the X" is the one an instruction does not fix.** It survived at the same rate with this
+skill and without it (11 drafts against 10, over 72). Use the test rather than the row: if deleting
+"name" leaves a sentence that says what happens, delete it; if it does not, you were about to write
+a verb for an action you had not decided on.
+
+Three phrases were cut from this table because the same count found zero uses of them in a day:
+"move the needle", "drive it to zero", "surface the issue". A rule against a phrase nobody writes
+costs a reader attention and buys nothing.
+
+## Untested, and here because the fault is the same
+
+These were measured at 0 of 72 drafts in both arms, so this skill has no evidence that naming them
+changes anything. They stay as examples, not as rules:
+
+- **A verb with no actor.** "The fix is being prioritised." Who is doing it, and when?
+- **A noun that should be a number.** "Significant improvement." From what to what?
+- **A promise with no object.** "We will follow up." On what, with whom, by when?
+- **A hedge that costs the reader a second read.** "It may be worth considering whether we should."
+  Either recommend it or do not raise it.
+
+**Where this skill helps, measured:** over 72 drafts of six real status messages, when the writer
+works from notes it went from 16 of 18 clean to 18 of 18. When the task was already prose, both arms
+were 18 of 18. So it earns its place where an agent writes up its own work, which is where these
+phrases live.
+
+## Do not shout
+
+The operator, on an ask written in capitalised headers: why do you keep writing your asks in this
+obnoxious format with all caps headers and stuff?
+
+No capitalised headers. No capitalised phrases for emphasis. Bold only where a number, a name or a
+choice needs to be found again.
+
+The reason it appears: an agent writes a long passage, cannot find its point, and puts a handle on
+it so a reader can. **The handle is a symptom. Cut the passage instead.** A paragraph that needs a
+shouted header to be skimmable is a paragraph nobody should have to skim.
+
+The same goes for a message to another agent. A capitalised line in a brief reads as an instruction
+shouted twice, and a reader who sees three of them stops seeing any.
+
+## What stays
+
+Plain verbs that describe a real action stay: merge, delete, send, read, measure, kill a process by
+pid, repoint a link. The rule is against phrases that sound like an action and name none.
+
+A term of art stays when it is the literal name of the thing: a merge queue merges, a garbage
+collector collects, a sweep sweeps.
+
+## Where this fits
+
+`skill://asd-ste100` constrains grammar and vocabulary for a reader whose first language may not be
+English. This skill removes verb phrases that carry no fact. Neither removes AI writing tells, so
+where your session has a pass for those it is a third one. Run them all on an outside message
+(`skill://outside-message`); run this one on everything.

package/src/channel-forwarder.ts

@@ -0,0 +1,262 @@
+import type { RelayHeaders } from "@legion/envoy-client/consumer-delivery"
+import {
+  createDeliveryDedupe,
+  type DedupeIdentity,
+  DedupeIdentitySchema,
+  type DeliveryDedupe,
+  readArrivals,
+} from "@legion/envoy-client/delivery"
+import { messageFor } from "@legion/envoy-client/errors"
+import { expandSubscriptionTopics } from "@legion/envoy-client/transport"
+import { z } from "zod"
+
+/** A message as the broker yields it (a nats.js `Msg` satisfies this). */
+export interface ChannelBrokerMessage {
+  readonly subject: string
+  readonly data: Uint8Array
+  readonly reply?: string
+  /** The message's NATS headers; only a relay frame (consumer delivery) carries any read here. */
+  readonly headers?: RelayHeaders
+}
+
+/** A broker message as the forwarder delivers it: decoded once and classified. */
+export interface ChannelInboundMessage extends ChannelBrokerMessage {
+  /** `data` decoded as UTF-8 once, at the broker boundary. */
+  readonly raw: string
+  /**
+   * The event already reached the channel queue, or its relayed copy is the one shown
+   * (`ChannelForwarderOptions.relayed`); direct request-reply still needs its receipt.
+   */
+  readonly duplicate?: true
+  /**
+   * The topic the envelope itself names. It differs from `subject` when the listener forwarded
+   * a lane (a role topic) onto the direct subject and is waiting for a receipt.
+   */
+  readonly envelopeTopic?: string
+}
+
+export interface ChannelTopicSubscription extends AsyncIterable<ChannelBrokerMessage> {
+  unsubscribe(): void
+}
+
+/** A nats.js connection status event; only its `type` is read. */
+export interface ChannelConnectionStatus {
+  readonly type: string
+}
+
+/** The NATS connection surface used by a channel session. */
+export interface ChannelForwarderConnection {
+  subscribe(subject: string): ChannelTopicSubscription
+  publish(subject: string, data: Uint8Array): void
+  flush(): Promise<void>
+  isClosed(): boolean
+  drain(): Promise<void>
+  close(): Promise<void>
+  /** The connection's status events (nats.js `status()`), which end when it closes. */
+  status(): AsyncIterable<ChannelConnectionStatus>
+}
+
+export interface ChannelForwarder {
+  /** Start delivering a topic; a topic already followed is left alone. */
+  follow(topic: string): void
+  /** Stop delivering the given topics, or every topic when the list is empty. */
+  unfollow(topics: readonly string[]): Promise<void>
+  /** Topics currently delivered, in follow order. */
+  topics(): readonly string[]
+  /** True once the connection is closed for good. */
+  isClosed(): boolean
+  /** Stop every subscription and drain the NATS connection; never rejects. */
+  close(): Promise<void>
+}
+
+/** The replay ledger as the live path sees it (`@legion/envoy-client/replay`). */
+export interface ChannelForwarderLedger {
+  /** Whether the session was shown the frame already, before this process started included. */
+  delivered(frame: DedupeIdentity): boolean
+  /** Records a frame Claude Code was handed, so no replay shows it again; never rejects. */
+  recordDelivered(frame: DedupeIdentity): Promise<void>
+}
+
+export interface ChannelForwarderOptions {
+  /**
+   * Hands one frame on and resolves whether Claude Code got it; `false`, or a rejection, releases
+   * the frame's dedupe claim, so a re-send of it still arrives.
+   */
+  readonly deliver: (message: ChannelInboundMessage) => Promise<boolean>
+  /** How long close waits for a broker drain before closing outright. */
+  readonly drainTimeoutMs?: number
+  /** The claims of the live path; a replay engine reads them to leave a frame in flight alone. */
+  readonly dedupe?: DeliveryDedupe
+  readonly ledger?: ChannelForwarderLedger
+  /**
+   * A frame whose delivery rejected, after its claim was released: `topic` is the subscription it
+   * came on, which says whether a replay will show it again, and `receivedAt` when the
+   * subscription yielded it (`Date.now`, `readArrivals`), however long the frames before it took
+   * to deliver, which says whether a replay cursor started past it.
+   */
+  readonly failed?: (
+    message: ChannelInboundMessage,
+    topic: string,
+    error: unknown,
+    receivedAt: number,
+  ) => void
+  /**
+   * Whether the listener relays the subscription `topic`'s subject from the session's consumer
+   * (consumer delivery), which shows its frames: a core frame on it claims nothing and goes on as
+   * a duplicate, only to answer a lane's receipt. Read before the claim, so the core copy never
+   * holds the claim its relayed copy needs.
+   */
+  readonly relayed?: (topic: string) => boolean
+}
+
+interface Following {
+  readonly subscription: ChannelTopicSubscription
+  readonly done: Promise<void>
+}
+
+// A delivery's identity fields parse independently: a field the shared rule refuses identifies
+// nothing, and its valid sibling can still recognise a repeat. `topic` follows the same rule
+// before it is exposed as the envelope topic.
+const DeliveryIdentity = DedupeIdentitySchema.extend({
+  event_id: DedupeIdentitySchema.shape.event_id.catch(undefined),
+  dedupe_key: DedupeIdentitySchema.shape.dedupe_key.catch(undefined),
+  source: DedupeIdentitySchema.shape.source.catch(undefined),
+  source_event_id: DedupeIdentitySchema.shape.source_event_id.catch(undefined),
+  topic: z.string().min(1).optional().catch(undefined),
+})
+
+const decoder = new TextDecoder()
+const DEFAULT_DRAIN_TIMEOUT_MS = 1_000
+
+/** A frame's identity fields, each kept only when valid; undefined for a frame that is not JSON. */
+export function deliveryIdentity(raw: string): z.infer<typeof DeliveryIdentity> | undefined {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+  const identity = DeliveryIdentity.safeParse(parsed)
+  return identity.success ? identity.data : undefined
+}
+
+function report(what: string, error: unknown): void {
+  process.stderr.write(`envoy-channel: ${what} — ${messageFor(error)}\n`)
+}
+
+/**
+ * One channel process receives both its direct Envoy route and every followed
+ * topic. It deduplicates at the broker boundary, by event id and by dedupe key,
+ * so an event covered by several patterns, and a re-send of one already
+ * delivered, still becomes one Claude Code channel notification. With a replay
+ * ledger, a frame the session was shown before this process started is dropped
+ * too, and each frame handed on is recorded there before its claim settles.
+ */
+export function createChannelForwarder(
+  connection: ChannelForwarderConnection,
+  options: ChannelForwarderOptions,
+): ChannelForwarder {
+  const following = new Map<string, Following>()
+  const dedupe = options.dedupe ?? createDeliveryDedupe()
+  const drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS
+
+  const deliver = async (topic: string, subscription: ChannelTopicSubscription): Promise<void> => {
+    try {
+      for await (const { message, receivedAt } of readArrivals(subscription)) {
+        const raw = decoder.decode(message.data)
+        const identity = deliveryIdentity(raw)
+        // The relay shows this subject's frames: the core copy answers only a lane's receipt.
+        let claim = options.relayed?.(topic) === true ? undefined : dedupe.claim(identity)
+        // A repeat of a frame the session was shown before this process started, which only the
+        // replay ledger knows of: it goes on as a duplicate, which still answers a lane's receipt.
+        if (claim !== undefined && identity !== undefined && options.ledger?.delivered(identity)) {
+          claim.settle()
+          claim = undefined
+        }
+        // A nats.js Msg exposes subject/data/reply through prototype getters,
+        // which an object spread would silently drop; copy the fields by name.
+        const inbound: ChannelInboundMessage = {
+          subject: message.subject,
+          data: message.data,
+          raw,
+          // nats.js MsgImpl.reply is a getter returning "" when unset; absent means no reply address.
+          ...(message.reply ? { reply: message.reply } : {}),
+          ...(identity?.topic === undefined ? {} : { envelopeTopic: identity.topic }),
+          ...(claim === undefined ? { duplicate: true } : {}),
+        }
+        let handed: boolean
+        try {
+          handed = await options.deliver(inbound)
+        } catch (error) {
+          claim?.release()
+          report(`could not deliver a message on ${message.subject}`, error)
+          // A duplicate was never being shown; only its receipt can have failed.
+          if (claim !== undefined) options.failed?.(inbound, topic, error, receivedAt)
+          continue
+        }
+        if (claim === undefined) continue
+        if (!handed) {
+          claim.release()
+          continue
+        }
+        // Recorded before the claim settles, so a replay never finds the frame neither pending
+        // nor in the ledger and shows it a second time. The next frame does not wait for the
+        // write: a repeat of this one meanwhile still finds its claim.
+        const taken = claim
+        const settle = () => taken.settle()
+        if (identity === undefined || options.ledger === undefined) settle()
+        else void options.ledger.recordDelivered(identity).then(settle, settle)
+      }
+    } catch (error) {
+      report(`delivery from ${topic} stopped`, error)
+    }
+  }
+
+  const stop = async (topics: readonly string[]): Promise<void> => {
+    const stopping = topics.flatMap((topic) => {
+      const entry = following.get(topic)
+      if (entry === undefined) return []
+      following.delete(topic)
+      entry.subscription.unsubscribe()
+      return [entry.done]
+    })
+    await Promise.all(stopping)
+  }
+
+  return {
+    follow(topic) {
+      for (const subject of expandSubscriptionTopics([topic])) {
+        if (following.has(subject)) continue
+        const subscription = connection.subscribe(subject)
+        following.set(subject, { subscription, done: deliver(subject, subscription) })
+      }
+    },
+    unfollow(topics) {
+      return stop(topics.length === 0 ? [...following.keys()] : expandSubscriptionTopics(topics))
+    },
+    topics() {
+      return [...following.keys()]
+    },
+    isClosed() {
+      return connection.isClosed()
+    },
+    async close() {
+      await stop([...following.keys()])
+      if (connection.isClosed()) return
+      const timeout = Promise.withResolvers<void>()
+      const timer = setTimeout(timeout.resolve, drainTimeoutMs)
+      try {
+        await Promise.race([connection.drain(), timeout.promise])
+      } catch (error) {
+        report("draining the broker connection failed", error)
+      }
+      clearTimeout(timer)
+      if (connection.isClosed()) return
+      try {
+        await connection.close()
+      } catch (error) {
+        report("closing the broker connection failed", error)
+      }
+    },
+  }
+}