typeclaw 0.23.0 → 0.24.0

package/src/server/index.ts

@@ -17,6 +17,14 @@ import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-hand
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
+import { TODO_CONTINUATION_SOURCE } from '@/agent/todo/continuation'
+import {
+  armRestartKickForOrigin,
+  extractTurnUsage,
+  recordTurnOutcome,
+  recordTurnStart,
+  runIdleContinuation,
+} from '@/agent/todo/continuation-wiring'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
 import type { McpManager } from '@/mcp'
@@ -155,6 +163,7 @@ type QueuedPrompt = {
   text: string
   delivery: PromptDelivery
   ts: number
+  source?: string
 }
 
 type SessionState = {
@@ -172,6 +181,7 @@ type SessionState = {
   // generation that ran session.start. A plugin reload mid-connection does
   // not re-target this session's lifecycle hooks.
   runtimeSnapshot: PluginRuntimeState | null
+  unsubTurnOutcome: Unsubscribe | null
   dispose: () => Promise<void>
 }
 
@@ -257,7 +267,7 @@ export function createServer({
       handoffPending = false
       return null
     }
-    handoffInFlight = consumeRestartHandoff(agentDir).catch(() => null)
+    handoffInFlight = consumeRestartHandoff(agentDir, { accept: (h) => h.origin.kind === 'tui' }).catch(() => null)
     const result = await handoffInFlight
     handoffPending = false
     handoffInFlight = null
@@ -497,6 +507,7 @@ export function createServer({
               unsubClaim: null,
               activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
+              unsubTurnOutcome: null,
               dispose,
             }
             sessionStates.set(ws, state)
@@ -505,12 +516,16 @@ export function createServer({
               await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
             }
 
+            if (agentDir !== undefined) {
+              state.unsubTurnOutcome = subscribeTurnOutcome(session, agentDir, origin, sessionFileId, logger)
+            }
+
             liveSessionRegistry?.register({ sessionId: sessionFileId, session })
             forwardSessionEvents(ws, session, logger, sessionFileId)
 
             if (stream) {
               state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-                enqueuePrompt(ws, state, msg, agentDir, logger),
+                enqueuePrompt(ws, state, msg, agentDir, logger, stream),
               )
 
               state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -543,6 +558,17 @@ export function createServer({
             // wired (state.unsubPrompts above) so the kick is enqueued, not
             // dropped on the floor.
             if (resumed !== null && stream) {
+              // Arm the one-shot restart-kick suppressor BEFORE publishing the
+              // kick: the kick owns the first post-restart turn ("I'm back"),
+              // so the first idle after it must not also fire a todo
+              // continuation. The flag is consumed by that first idle. Best-
+              // effort: a failure here only risks one redundant nudge, which
+              // the episode budget still bounds.
+              if (agentDir !== undefined) {
+                await armRestartKickForOrigin(agentDir, origin).catch((err) =>
+                  logger.error(`[server] ${sessionFileId}: arm restart-kick suppression failed: ${describeErr(err)}`),
+                )
+              }
               stream.publish({
                 target: { kind: 'session', sessionId: sessionFileId },
                 payload: { kind: 'prompt', text: ' ', delivery: 'queue' },
@@ -798,6 +824,7 @@ export function createServer({
             }
           } finally {
             if (state) {
+              state.unsubTurnOutcome?.()
               state.session.dispose()
               await state.dispose()
               liveSessionRegistry?.unregister(state.sessionFileId)
@@ -867,6 +894,31 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
   })
 }
 
+// Record each completed turn's stopReason for the todo-continuation guard.
+// Ordering-independent by design: this writes the outcome from `message_end`,
+// and the idle path only reads the stored outcome — it never assumes the
+// event arrived before idle fired. An unrecognized stopReason classifies as
+// 'unknown', which the idle path treats as not-safe-to-continue (fail closed).
+function subscribeTurnOutcome(
+  session: AgentSession,
+  agentDir: string,
+  origin: SessionOrigin,
+  sessionFileId: string,
+  logger: ServerLogger,
+): Unsubscribe {
+  return session.subscribe((event) => {
+    const usage = extractTurnUsage(event)
+    if (usage === null) return
+    void recordTurnOutcome({
+      agentDir,
+      origin,
+      turnId: sessionFileId,
+      stopReason: usage.stopReason,
+      ...(usage.tokens !== undefined ? { tokens: usage.tokens } : {}),
+    }).catch((err) => logger.error(`[server] ${sessionFileId}: todo outcome capture failed: ${describeErr(err)}`))
+  })
+}
+
 function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
   const detected = detectProviderError(message)
   if (detected === null) return
@@ -895,6 +947,7 @@ function enqueuePrompt(
   msg: StreamMessage,
   agentDir: string | undefined,
   logger: ServerLogger,
+  stream: Stream | undefined,
 ): void {
   const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
   if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
@@ -904,14 +957,16 @@ function enqueuePrompt(
       send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
     })
   }
+  const source = (msg.meta as { source?: unknown } | undefined)?.source
   state.drainQueue.push({
     streamMessageId: msg.id,
     text: payload.text,
     delivery,
     ts: msg.ts,
+    ...(typeof source === 'string' ? { source } : {}),
   })
   pushQueueState(ws, state)
-  void drain(ws, state, agentDir, logger)
+  void drain(ws, state, agentDir, logger, stream)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -948,7 +1003,13 @@ function makeTurnHookCallers(
   }
 }
 
-async function drain(ws: Ws, state: SessionState, agentDir: string | undefined, logger: ServerLogger): Promise<void> {
+async function drain(
+  ws: Ws,
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+  stream: Stream | undefined,
+): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
@@ -960,6 +1021,14 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
+      if (agentDir !== undefined) {
+        await recordTurnStart({
+          agentDir,
+          origin: state.origin,
+          isRealUserTurn: item.source !== TODO_CONTINUATION_SOURCE,
+        }).catch((err) => logger.error(`[server] ${state.sessionFileId}: todo turn-start failed: ${describeErr(err)}`))
+      }
+
       await fireTurnStart(item.text)
       try {
         await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
@@ -971,12 +1040,57 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       }
       await fireTurnEnd()
       await fireIdle()
+
+      // Idle-continuation runs INSIDE the loop and enqueues directly onto
+      // drainQueue (not via stream.publish). Publishing would re-enter drain()
+      // through the session subscriber while `state.draining` is still true, so
+      // the nested call would no-op and the continuation would stall until some
+      // unrelated event woke the loop again. Enqueuing here lets the same `while`
+      // consume it on the next iteration. Only fires when the queue is otherwise
+      // empty so a real user turn is never preempted by a continuation.
+      if (state.drainQueue.length === 0) {
+        await maybeContinueTodos(state, agentDir, logger)
+      }
     }
   } finally {
     state.draining = false
   }
 }
 
+// If incomplete todos remain and all guards pass, push a single continuation
+// prompt directly onto this session's drainQueue, tagged TODO_CONTINUATION_SOURCE
+// so the next drain iteration treats it as an injected (non-user) turn that does
+// not reset the episode budget. The enclosing drain loop consumes it; this never
+// calls drain() itself.
+async function maybeContinueTodos(
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+): Promise<void> {
+  if (agentDir === undefined) return
+  try {
+    await runIdleContinuation({
+      agentDir,
+      origin: state.origin,
+      deliver: (text) => {
+        state.drainQueue.push({
+          streamMessageId: `todo-continuation-${crypto.randomUUID()}` as StreamMessageId,
+          text,
+          delivery: 'queue',
+          ts: Date.now(),
+          source: TODO_CONTINUATION_SOURCE,
+        })
+      },
+    })
+  } catch (err) {
+    logger.error(`[server] ${state.sessionFileId}: todo continuation failed: ${describeErr(err)}`)
+  }
+}
+
+function describeErr(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 function pushQueueState(ws: Ws, state: SessionState): void {
   const pending: QueueStateItem[] = state.drainQueue.map((q) => ({
     id: q.streamMessageId,

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-github
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as an inline review via `gh api`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. When a review comment **you authored** gets addressed — the author pushed a fix or replied that resolves it — verify the fix at the PR's head SHA and then resolve the thread with the `resolveReviewThread` GraphQL mutation (see "Resolving review threads you authored" below); resolving is the close-out that tells the author the concern is settled. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as an inline review via `gh api`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. When a review comment **you authored** gets addressed — the author pushed a fix or replied that resolves it — verify the fix at the PR's head SHA and then resolve the thread by acknowledging with `channel_reply({ …, resolve_review_thread: true })`, which resolves the thread before posting the reply (see "Resolving review threads you authored" below); resolving is the close-out that tells the author the concern is settled. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
 ---
 
 GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -8,7 +8,7 @@ GitHub renders normal Markdown in issues, PRs, discussions, and review comments.
 - Do not send attachments on GitHub chats; the adapter rejects them.
 - There is no typing indicator.
 - For PR review threads, keep `thread` set to reply in-place. Omit `thread` for a top-level PR/issue comment.
-- When a review comment **you authored** has been addressed, resolve its thread — see "Resolving review threads you authored" below. The base principle is **whoever opened the thread closes it**: you resolve only the threads you started, never a human's.
+- When a review comment **you authored** has been addressed, resolve its thread by replying with `channel_reply({ …, resolve_review_thread: true })` — see "Resolving review threads you authored" below. The base principle is **whoever opened the thread closes it**: you resolve only the threads you started, never a human's (the runtime enforces this).
 
 ## Mid-turn status replies need `continue: true`
 
@@ -43,6 +43,10 @@ A `review_request_removed` inbound ("removed your review request on PR #N") is t
 
 The `reviewer` subagent is the analyst; you are the integration layer between its output and GitHub's review API. It loads the `code-review` skill on demand and returns line-anchored findings inside a `<review>` block. Your job is mechanics: spawn, wait, translate, post.
 
+**The reviewer's `<review>` block is the only source of the verdict and the findings.** You do not review the PR yourself. Between spawning the reviewer and reading its result you do **no analysis of this PR** — do not run `gh pr diff`, do not read the changed files to form an opinion, do not draft a verdict. The reviewer runs on the `deep` model precisely so this judgment is not yours to make on the parent model. If you analyze the diff and post your own assessment while the reviewer is still running, you will post one verdict now and the reviewer's (often different) verdict when it completes — **two contradictory reviews on the same PR**, the exact failure this flow exists to prevent. Wait for the reviewer; post what it returns; nothing before that.
+
+**HARD RULE — a review with actionable findings is a formal review, never a flat comment.** If the reviewer returns **one or more** actionable findings (`blocker`/`concern`/`nit`), the ONLY acceptable way to deliver them is a formal review via `POST /pulls/<N>/reviews` (step 4) — `REQUEST_CHANGES`, `COMMENT`, or `APPROVE` per the verdict, with the line-anchored findings in `comments[]`. You may **never** flatten those findings into a `channel_reply` or a top-level issue comment, **even when** the `gh api` call fails. A 422 means an anchor is wrong (almost always a `line` not in the diff): re-anchor it or move that one finding into the top-level review `body`, then resubmit the formal review — do **not** abandon the formal review and post prose instead. A flat "## Review … two blockers" comment is a bug, not a fallback: it strands the findings without line anchors and is the exact failure this rule exists to prevent. The flat/issue-comment path is reserved for the **zero-actionable-findings** branch only (see below). If you genuinely cannot land a formal review after fixing anchors, say so plainly and post nothing that claims a review happened — silence beats a false receipt.
+
 1. **Confirm the target, and check whether you already reviewed it.** Capture the PR number, the repo, and the head SHA — you may need the SHA to read files at the revision the reviewer analyzed.
 
    ```sh
@@ -65,9 +69,15 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
    **If step 1 found a prior `CHANGES_REQUESTED` review, say so in the spawn payload** — e.g. _"This is a re-review: you previously requested changes on this PR (the prior blockers were …). Verify they are resolved and return `approve` or `request-changes` — a re-review must re-decide the blocking state, not return `comment`."_ The reviewer's `code-review` skill enforces the same rule, but telling it the prior verdict is what lets it apply that rule; a fresh reviewer session has no memory of your earlier review.
 
-   Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true` and keep working; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
+   Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true`; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
+
+   After spawning, **end your turn** — the background reviewer wakes you with a completion `<system-reminder>` (step 3). "Stay responsive" means you remain free to handle _other_ chats meanwhile; it does **not** license you to keep working _this_ PR. Do not poll `subagent_output` in a busy-wait, and do not fill the wait by reviewing the diff yourself (see the exclusivity rule at the top of this flow). The next thing you do on this PR is read the reviewer's `<review>` block when the reminder arrives.
+
+3. **On the completion `<system-reminder>`, first check you have not already posted — then** call `subagent_output({ task_id })` to read the reviewer's final assistant message.
 
-3. **Wait for the completion `<system-reminder>`,** then call `subagent_output({ task_id })` to read the reviewer's final assistant message. The structured payload looks like:
+   **One verdict per PR per request — guard this before you read or post anything.** The completion reminder is not a license to post; it is a wake-up. The very first thing you do on this turn is ask: have I **already posted a review or verdict on this PR during this engagement**? If yes, stop here — do not fetch the reviewer output, do not translate, do not post. Call `skip_response({ reason: "review already posted for this PR" })` and end the turn. Posting the reminder's result on top of a verdict you already shipped is how a PR ends up with two reviews — and if the two disagree (because the earlier one was your own premature take), it contradicts you in public. Only when no review has gone out yet do you proceed to read and post below — which is the normal path, since you waited for the reviewer instead of reviewing it yourself.
+
+   With that confirmed, read the reviewer's final assistant message. The structured payload looks like:
 
    ```xml
    <review>
@@ -174,11 +184,28 @@ Do not resolve on a bare "done" claim. A reply that says "fixed" is a prompt to
 2. Read the lines your comment anchored to, at that SHA: `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>` (or `gh pr diff <N>` to see what the new push changed). Confirm the change actually addresses the concern your comment raised — not a different line, not a partial fix.
 3. Only when the code at head genuinely resolves the finding do you resolve the thread. If the fix is partial or misses the point, **reply in the thread** explaining what's still open and leave it unresolved.
 
-If the author merely **replied** without pushing (e.g. "this is intentional because …") and their reasoning settles it, that is also "addressed" — **resolve first, then optionally leave a one-line acknowledgement.** Order matters: a bare `channel_reply` ends your turn (see "Mid-turn status replies need `continue: true`" above), so acknowledging _before_ you resolve would stop the turn and the `resolveReviewThread` mutation would never run, leaving the thread open. Resolve, then reply. If you genuinely want to acknowledge before resolving, the acknowledgement must use `channel_reply({ …, continue: true })` so the turn survives long enough to resolve. If their reasoning does **not** settle it, keep the thread open and answer.
+If the author merely **replied** without pushing (e.g. "this is intentional because …") and their reasoning settles it, that is also "addressed". If their reasoning does **not** settle it, keep the thread open and answer instead.
+
+### How to resolve — `channel_reply({ resolve_review_thread: true })`
+
+Once you have verified the fix, **acknowledge and resolve in one call**: pass `resolve_review_thread: true` to your `channel_reply`. The runtime resolves the thread you're replying in **before** it posts your acknowledgement, then posts the reply:
+
+```
+channel_reply({ text: "Verified — the fix addresses the concern. Thanks!", resolve_review_thread: true })
+```
+
+This is the correct path and it removes a footgun. A bare `channel_reply` ends your turn the moment it lands, so a resolve attempted _after_ the acknowledgement would never run — the thread would stay open even though you "handled" it. The flag resolves first, so a normal final reply still closes the thread. You do **not** need `continue: true` for this: resolution happens inside the same call, before the turn ends.
+
+Two guarantees make the flag safe to use as your default:
+
+- **Author check is enforced in code.** The runtime only resolves a thread whose root comment **you** authored; a request to resolve a human reviewer's thread is refused, and the reply is **not** posted. You cannot accidentally close someone else's open question.
+- **A failed resolve blocks the reply.** If the resolve fails (permission denied, wrong author, the fix doesn't verify on the API side), `channel_reply` is denied and posts nothing — so you never end up with a cheerful "looks resolved" comment sitting next to a still-open thread. Read the denial, fix the cause, and retry.
+
+The flag is valid only on a github session replying inside a thread (`thread` set on the origin). It is ignored — and denied — elsewhere. If the thread is already resolved or already gone, the reply still posts (nothing left to close).
 
-### How to resolve — `resolveReviewThread` GraphQL mutation
+### Fallback — the raw `resolveReviewThread` GraphQL mutation
 
-There is no REST endpoint for this. Resolution is a GraphQL mutation that takes the thread's **node id** (`PRRT_…`), not the comment's numeric id. Two steps: find the thread id, then resolve it.
+Prefer the flag above. Reach for the raw mutation only when you need to resolve a thread you are **not** currently replying in, or to debug. There is no REST endpoint for this. Resolution is a GraphQL mutation that takes the thread's **node id** (`PRRT_…`), not the comment's numeric id. Two steps: find the thread id, then resolve it.
 
 1. **Find the node id of the thread you authored.** Query the PR's review threads and pick the one whose root comment is yours and matches the `thread` you're replying in:
 

package/typeclaw.schema.json

@@ -548,10 +548,20 @@
             },
             "review": {
               "default": {
+                "on": "review_requested",
                 "approve": true
               },
               "type": "object",
               "properties": {
+                "on": {
+                  "default": "review_requested",
+                  "type": "string",
+                  "enum": [
+                    "review_requested",
+                    "opened",
+                    "off"
+                  ]
+                },
                 "approve": {
                   "default": true,
                   "type": "boolean"