runcastle 1.4.8 → 1.5.4

package/drizzle/meta/_journal.json

@@ -316,6 +316,69 @@
       "when": 1790860897661,
       "tag": "0044_icy_daimon_hellstrom",
       "breakpoints": true
+    },
+    {
+      "idx": 45,
+      "version": "6",
+      "when": 1792053714532,
+      "tag": "0045_nappy_adam_destine",
+      "breakpoints": true
+    },
+    {
+      "idx": 46,
+      "version": "6",
+      "when": 1792224938618,
+      "tag": "0046_project_scenario_runner",
+      "breakpoints": true
+    },
+    {
+      "idx": 47,
+      "version": "6",
+      "when": 1792228865475,
+      "tag": "0046_polite_nightcrawler",
+      "breakpoints": true
+    },
+    {
+      "idx": 48,
+      "version": "6",
+      "when": 1792301267550,
+      "tag": "0047_clear_betty_brant",
+      "breakpoints": true
+    },
+    {
+      "idx": 49,
+      "version": "6",
+      "when": 1792345583347,
+      "tag": "0048_new_northstar",
+      "breakpoints": true
+    },
+    {
+      "idx": 50,
+      "version": "6",
+      "when": 1792482127192,
+      "tag": "0050_tan_manta",
+      "breakpoints": true
+    },
+    {
+      "idx": 51,
+      "version": "6",
+      "when": 1792569018654,
+      "tag": "0051_ambiguous_talkback",
+      "breakpoints": true
+    },
+    {
+      "idx": 52,
+      "version": "6",
+      "when": 1792847895970,
+      "tag": "0052_friendly_black_tarantula",
+      "breakpoints": true
+    },
+    {
+      "idx": 53,
+      "version": "6",
+      "when": 1792865670658,
+      "tag": "0053_soft_karma",
+      "breakpoints": true
     }
   ]
 }

package/hook-client.ts

@@ -5,12 +5,23 @@
  * It reads the hook JSON from stdin, POSTs `{ event, sessionId, payload }` to
  * `RUNCASTLE_SERVER_URL/api/hooks/<event>`, and prints the server's response body
  * VERBATIM to stdout (the server returns the final hook JSON that Claude Code
- * consumes as context). Zero dependencies (plain `fetch`), 3s timeout. On ANY
+ * consumes as context). Zero dependencies (plain `fetch`), 3s timeout (5s and
+ * retried for `session-start`, see {@link postHook}). On ANY
  * error it prints `{}` and exits 0 — a hook must never break the user's session.
+ *
+ * One argument is not a route event: `wait-messages`, the background message
+ * waiter of the orchestrator and of a feature's lead (see {@link waitMessages}).
  */
 
 const FETCH_TIMEOUT_MS = 3000
 const STDIN_TIMEOUT_MS = 2500
+/**
+ * `session-start` is retried ({@link postHook}): 3 attempts of 5s with a 0.5s
+ * pause stay inside the 20s its settings give it (`renderSettings`).
+ */
+const SESSION_START_ATTEMPTS = 3
+const SESSION_START_FETCH_TIMEOUT_MS = 5000
+const SESSION_START_RETRY_MS = 500
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = []
@@ -33,11 +44,70 @@ async function readStdin(): Promise<string> {
   })
 }
 
+/** The hook-client argument that runs the orchestrator's message waiter. */
+export const WAIT_MESSAGES_MODE = 'wait-messages'
+
+/** Longer than the server's hold, so a held poll is answered rather than cut off. */
+const WAIT_FETCH_TIMEOUT_MS = 40_000
+/** The pause after a failed poll (server restarting, network blip) before the next. */
+const WAIT_RETRY_MS = 3000
+
+export interface WaitMessagesDeps {
+  fetch?: typeof fetch
+  sleep?: (ms: number) => Promise<void>
+  waiterId?: string
+}
+
+/**
+ * `wait-messages` mode (`whole-cuts-plan-themselves` decision 20). Runs as an
+ * orchestrate session's `asyncRewake` hook: long-polls
+ * `GET /api/hooks/orchestrator-messages` until the server hands it lines, then
+ * resolves exit code 2 with them joined by newlines — Claude Code wakes the
+ * session with that output as one system reminder. `superseded` (a newer waiter
+ * took over) and `ended` (the session is over) resolve 0 with nothing to say. A
+ * hold that ran out polls again; a failed poll waits and retries. Never 2
+ * without lines.
+ */
+export async function waitMessages(
+  serverUrl: string,
+  sessionId: string | undefined,
+  deps: WaitMessagesDeps = {},
+): Promise<{ code: 0 | 2; output: string }> {
+  if (!sessionId) return { code: 0, output: '' }
+  const doFetch = deps.fetch ?? fetch
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+  const waiter = deps.waiterId ?? crypto.randomUUID()
+  const url =
+    `${serverUrl}/api/hooks/orchestrator-messages` +
+    `?sessionId=${encodeURIComponent(sessionId)}&waiter=${encodeURIComponent(waiter)}`
+  for (;;) {
+    let answer: { status?: string; lines?: unknown }
+    try {
+      const res = await doFetch(url, { signal: AbortSignal.timeout(WAIT_FETCH_TIMEOUT_MS) })
+      answer = (await res.json()) as typeof answer
+    } catch {
+      await sleep(WAIT_RETRY_MS)
+      continue
+    }
+    if (answer.status === 'superseded' || answer.status === 'ended') return { code: 0, output: '' }
+    const lines = Array.isArray(answer.lines) ? answer.lines.filter((l) => typeof l === 'string') : []
+    if (answer.status === 'lines' && lines.length > 0) return { code: 2, output: lines.join('\n') }
+    // Anything but a hold that ran out answered at once: never spin on it.
+    if (answer.status !== 'empty') await sleep(WAIT_RETRY_MS)
+  }
+}
+
 export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
   const event = argv[0] ?? ''
   const serverUrl = process.env.RUNCASTLE_SERVER_URL ?? 'http://localhost:4512'
   const sessionId = process.env.RUNCASTLE_SESSION_ID
 
+  if (event === WAIT_MESSAGES_MODE) {
+    const { code, output } = await waitMessages(serverUrl, sessionId)
+    if (output) process.stderr.write(output)
+    process.exit(code)
+  }
+
   const raw = await readStdin()
   let payload: unknown
   try {
@@ -46,17 +116,48 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     payload = { raw }
   }
 
-  const res = await fetch(`${serverUrl}/api/hooks/${event}`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ event, sessionId, payload }),
-    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-  })
-
-  const text = await res.text()
+  const text = await postHook(serverUrl, event, { event, sessionId, payload })
   process.stdout.write(text.trim().length > 0 ? text : '{}')
 }
 
+export interface PostHookDeps {
+  fetch?: typeof fetch
+  sleep?: (ms: number) => Promise<void>
+}
+
+/**
+ * POST one hook to the server and return its response body. `session-start` is
+ * the one that records the conversation id every later resume needs, and its
+ * handler is idempotent (it already fires once per source), so a failed or
+ * timed-out attempt is retried: one slow server moment must not leave a session
+ * unrecorded. Every other hook gets one attempt — it blocks a turn or a tool.
+ */
+export async function postHook(
+  serverUrl: string,
+  event: string,
+  body: unknown,
+  deps: PostHookDeps = {},
+): Promise<string> {
+  const doFetch = deps.fetch ?? fetch
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+  const startHook = event === 'session-start'
+  const attempts = startHook ? SESSION_START_ATTEMPTS : 1
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const res = await doFetch(`${serverUrl}/api/hooks/${event}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(startHook ? SESSION_START_FETCH_TIMEOUT_MS : FETCH_TIMEOUT_MS),
+      })
+      return await res.text()
+    } catch (err) {
+      if (attempt >= attempts) throw err
+      await sleep(SESSION_START_RETRY_MS)
+    }
+  }
+}
+
 if (import.meta.main) {
   main().catch((err) => {
     // Never break the user's session: log, print `{}`, exit 0 (SPEC §5.5).