typeclaw 0.39.4 → 0.39.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.39.4",
3
+ "version": "0.39.5",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -715,11 +715,20 @@ export function detectAttentionEscalation(text: string, prior?: QuestionSignal |
715
715
  // unconditionally and gives OpenAI models maximum effort on escalation turns.
716
716
  const ESCALATED_LEVEL: ThinkingLevel = 'xhigh'
717
717
 
718
+ // `allowEscalation: false` pins the turn to `sessionDefault`. Subagent turns set
719
+ // it because their "user prompt" is composed by another agent, not a human — so
720
+ // the question-mark/frustration heuristics would misread a multi-question brief
721
+ // and silently bump a `fast`/`low` worker to `xhigh`. Default `true` keeps the
722
+ // human-facing sessions (TUI, channels, cron) escalating as before.
723
+ export type TurnThinkingOptions = { allowEscalation?: boolean }
724
+
718
725
  export function resolveTurnThinkingLevel(
719
726
  text: string,
720
727
  sessionDefault: ThinkingLevel | undefined,
721
728
  prior?: QuestionSignal | null,
729
+ options?: TurnThinkingOptions,
722
730
  ): ThinkingLevel | undefined {
731
+ if (options?.allowEscalation === false) return sessionDefault
723
732
  return detectAttentionEscalation(text, prior) ? ESCALATED_LEVEL : sessionDefault
724
733
  }
725
734
 
@@ -735,7 +744,8 @@ export function applyTurnThinkingLevel(
735
744
  text: string,
736
745
  sessionDefault: ThinkingLevel | undefined,
737
746
  prior?: QuestionSignal | null,
747
+ options?: TurnThinkingOptions,
738
748
  ): void {
739
- const resolved = resolveTurnThinkingLevel(text, sessionDefault, prior)
749
+ const resolved = resolveTurnThinkingLevel(text, sessionDefault, prior, options)
740
750
  if (resolved !== undefined) session.setThinkingLevel(resolved)
741
751
  }
@@ -338,7 +338,9 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
338
338
  retrievalContext.results.length > 0
339
339
  ? `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}\n\n${retrievalContext.results}`
340
340
  : `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`
341
- applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel)
341
+ applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel, undefined, {
342
+ allowEscalation: false,
343
+ })
342
344
  const result = await promptPersistentTurnWithFallback({
343
345
  refs: resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions)),
344
346
  currentModelRef: activeModelRef,
@@ -353,7 +355,9 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
353
355
  activeModelRef = ref
354
356
  },
355
357
  beforeAttempt: () => {
356
- applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel)
358
+ applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel, undefined, {
359
+ allowEscalation: false,
360
+ })
357
361
  },
358
362
  onAttemptFailed: (attempt) => {
359
363
  console.warn(
@@ -92,9 +92,9 @@ export function createChannelReplyTool({
92
92
  resolve_review_thread: Type.Optional(
93
93
  Type.Boolean({
94
94
  description:
95
- 'GitHub review threads ONLY — ignored on Slack, Discord, Telegram, KakaoTalk, and any non-github session, and ignored on a github reply that is not inside a `thread`. On those, leave this unset and ignore the rest of this description. ' +
96
- 'On a github reply inside a review thread you authored: when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"), treat setting this `true` as the expected close-out — do it in the SAME call. This is a strong instruction, not a schema requirement: the field stays optional and nothing rejects an acknowledgement that omits it, but a bare ack without it leaves the thread open, because a successful reply ends the turn and the resolve cannot run in a later one. So this flag is the only way the close-out actually happens. ' +
97
- "It is safe to set by default: the runtime resolves BEFORE posting and ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; just set it on your acknowledgement and let the runtime enforce ownership. Leave it unset when you intend to keep the thread open (partial fix, disagreement, mid-discussion).",
95
+ 'GitHub PR review threads ONLY. On a TERMINAL (`continue:false`) github PR review-thread reply that carries `text`, this is REQUIRED: you must set it to `true` or `false` and omitting it is rejected — you will be told to re-call with an explicit choice. (It stays a normal optional field everywhere else: ignored on Slack/Discord/Telegram/KakaoTalk and any non-github session, on github replies outside a review thread, on attachments-only replies, and on mid-turn `continue:true` status updates — leave it unset there.) ' +
96
+ 'Set `true` when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"): the runtime resolves the thread BEFORE posting, so the close-out actually happens in this same turn — a successful reply ends the turn, so a resolve deferred to "later" never runs. ' +
97
+ "Set `false` when the thread should stay open (partial fix, disagreement, mid-discussion). It is safe to set `true` by default: the runtime resolves ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; let the runtime enforce ownership.",
98
98
  }),
99
99
  ),
100
100
  }),
@@ -140,6 +140,27 @@ export function createChannelReplyTool({
140
140
  }
141
141
  }
142
142
 
143
+ // Required-choice guard: a terminal github review-thread text reply must
144
+ // make an explicit resolve_review_thread choice. The model kept silently
145
+ // omitting the flag after acknowledging a fix, leaving the thread open;
146
+ // forcing the choice (the discipline `continue` already enforces) closes
147
+ // the loop where prose instructions did not. The field stays optional in
148
+ // the schema precisely so omission is still detectable here (vs explicit
149
+ // false). Runs before the resolve/guards so a missing choice never acts.
150
+ const missingResolveChoice = missingReviewThreadResolveChoiceError({
151
+ origin,
152
+ text,
153
+ isContinue: keepTurnAlive,
154
+ resolveReviewThread: params.resolve_review_thread,
155
+ })
156
+ if (missingResolveChoice) {
157
+ logger.warn(formatChannelToolFailure('channel_reply', missingResolveChoice))
158
+ return {
159
+ content: [{ type: 'text' as const, text: `channel_reply denied: ${missingResolveChoice}` }],
160
+ details: { ok: false, error: missingResolveChoice },
161
+ }
162
+ }
163
+
143
164
  // False-receipt guard: deny a terminal reply that CLAIMS a PR verdict /
144
165
  // thread close-out the agent never actually performed this turn. Warn-tier
145
166
  // claims fall through and have their notice appended on success below.
@@ -279,6 +300,30 @@ export function createChannelReplyTool({
279
300
  })
280
301
  }
281
302
 
303
+ // Returns the denial string when a terminal github PR review-thread text reply
304
+ // omits an explicit resolve_review_thread choice, or '' when no choice is owed.
305
+ // Scoped by `^pr:\d+$` (not just thread !== null) so a future threaded github
306
+ // context can't be forced into a resolve choice that means nothing there.
307
+ function missingReviewThreadResolveChoiceError(input: {
308
+ origin: ChannelReplyOrigin
309
+ text: string | undefined
310
+ isContinue: boolean
311
+ resolveReviewThread: boolean | undefined
312
+ }): string {
313
+ const isGithubPrReviewThread =
314
+ input.origin.adapter === 'github' && /^pr:\d+$/.test(input.origin.chat) && input.origin.thread !== null
315
+ const hasText = input.text !== undefined && input.text.trim() !== ''
316
+ if (!isGithubPrReviewThread || !hasText || input.isContinue || input.resolveReviewThread !== undefined) {
317
+ return ''
318
+ }
319
+ return (
320
+ 'This is a terminal github PR review-thread reply with text, so `resolve_review_thread` is required: ' +
321
+ 'set it to `true` when the concern is fixed and this bot-authored thread should be closed (the runtime ' +
322
+ 'resolves before posting and only on your own thread), or `false` to leave it open. You omitted it; ' +
323
+ 're-call channel_reply with an explicit boolean.'
324
+ )
325
+ }
326
+
282
327
  // Returns an error string when the resolve should block the reply, or null
283
328
  // when it's safe to proceed. Only `no-match` (the thread is already gone, so
284
329
  // there's nothing to close) joins success as non-blocking; every hard failure
@@ -13,23 +13,58 @@
13
13
  // for the full rationale and AGENTS.md §"Web search" for the original story.
14
14
 
15
15
  import { curlImpersonate } from './curl-impersonate'
16
+ import { createKeyedSemaphore } from './keyed-semaphore'
17
+ import { type SearchRetryOptions, withSearchRetry } from './search-retry'
16
18
 
17
19
  export { _setCurlBinaryForTest } from './curl-impersonate'
18
20
 
19
21
  const DDG_LITE_URL = 'https://lite.duckduckgo.com/lite/'
20
22
 
23
+ // Empirically derived: a clean source IP serves DDG-lite at concurrency ~4 but
24
+ // trips a sticky multi-minute CAPTCHA at 5-6 (see keyed-semaphore.ts header).
25
+ // The whole agent egresses from one IP and the scout subagent fans out parallel
26
+ // searches, so 2 sits well under the observed ceiling with headroom for the
27
+ // concurrent membership-style overlap — matching the webex-prefetch-limiter
28
+ // default for the same reason.
29
+ export const DDG_CONCURRENCY = 2
30
+
31
+ // Process-wide, so the cap spans every session/subagent/cron in this agent.
32
+ const searchLimiter = createKeyedSemaphore({ concurrency: DDG_CONCURRENCY })
33
+
34
+ const DDG_KEY = 'ddg'
35
+
21
36
  export type DdgResult = {
22
37
  title: string
23
38
  url: string
24
39
  snippet: string
25
40
  }
26
41
 
42
+ type RetryOverride = Pick<SearchRetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'sleep'>
43
+ let retryOverride: RetryOverride = {}
44
+
45
+ // Test-only seam: lets *.test.ts collapse the generous production backoff to
46
+ // zero-delay single-shot retries so CAPTCHA tests don't burn real seconds.
47
+ // Production never calls this — the empty default above is what production sees.
48
+ export function _setSearchRetryForTest(override: RetryOverride | null): void {
49
+ retryOverride = override ?? {}
50
+ }
51
+
27
52
  export async function ddgSearch(query: string, limit: number, signal?: AbortSignal): Promise<DdgResult[]> {
28
- const html = await fetchDdgHtml(query, signal)
29
- if (isCaptcha(html)) {
30
- throw new DdgCaptchaError()
31
- }
32
- return parseDdgHtml(html).slice(0, limit)
53
+ return searchLimiter.run(
54
+ DDG_KEY,
55
+ () =>
56
+ withSearchRetry(
57
+ async () => {
58
+ const html = await fetchDdgHtml(query, signal)
59
+ if (isCaptcha(html)) {
60
+ throw new DdgCaptchaError()
61
+ }
62
+ return parseDdgHtml(html).slice(0, limit)
63
+ },
64
+ { ...retryOverride, shouldRetry: (error) => error instanceof DdgCaptchaError, signal },
65
+ ),
66
+ signal,
67
+ )
33
68
  }
34
69
 
35
70
  export class DdgCaptchaError extends Error {
@@ -0,0 +1,114 @@
1
+ // A process-wide keyed concurrency limiter: at most `concurrency` calls run
2
+ // at once PER KEY, and work queued behind a full key WAITS for a slot rather
3
+ // than being skipped. Distinct keys never contend.
4
+ //
5
+ // This is the queue-and-wait sibling of src/channels/adapters/webex-prefetch-
6
+ // limiter.ts. That limiter uses admit-or-skip because its work (history
7
+ // prefetch) is an optional context improvement — dropping it is fine. Here the
8
+ // work is a search the model explicitly asked for, so dropping it is NOT fine;
9
+ // callers must block until a slot frees.
10
+ //
11
+ // Why this exists: one typeclaw agent is one process, and all sessions
12
+ // (TUI, channel, cron, subagent) share that process. A search engine like
13
+ // DuckDuckGo rate-limits by source IP, and the whole agent egresses from one
14
+ // IP, so parallel searches across sessions/subagents stack onto the same
15
+ // per-engine budget. An empirical probe of lite.duckduckgo.com showed a clean
16
+ // IP serves ~4 concurrent requests but trips a sticky multi-minute CAPTCHA at
17
+ // 5-6 — and once tripped, even serial requests stay boxed. Capping concurrency
18
+ // PER ENGINE keeps the burst under that ceiling so the box is never tripped.
19
+
20
+ export type KeyedSemaphore = {
21
+ // Runs `work` once a slot for `key` is free, waiting if necessary. The slot
22
+ // is released when `work` settles (resolve or reject). Distinct keys run
23
+ // fully independently. If `signal` aborts while the call is still queued (or
24
+ // is already aborted on entry), the call rejects with SemaphoreAbortedError
25
+ // WITHOUT ever running `work` or holding a slot.
26
+ run<T>(key: string, work: () => Promise<T>, signal?: AbortSignal): Promise<T>
27
+ }
28
+
29
+ export type KeyedSemaphoreOptions = {
30
+ // Max concurrent runs PER KEY. Defaults to 1.
31
+ concurrency?: number
32
+ }
33
+
34
+ export class SemaphoreAbortedError extends Error {
35
+ constructor() {
36
+ super('Semaphore acquisition aborted before admission.')
37
+ this.name = 'SemaphoreAbortedError'
38
+ }
39
+ }
40
+
41
+ export function createKeyedSemaphore(options: KeyedSemaphoreOptions = {}): KeyedSemaphore {
42
+ const concurrency = Math.max(1, Math.floor(options.concurrency ?? 1))
43
+
44
+ type Waiter = () => void
45
+ type Pool = { active: number; waiters: Waiter[] }
46
+ const pools = new Map<string, Pool>()
47
+
48
+ const poolFor = (key: string): Pool => {
49
+ let pool = pools.get(key)
50
+ if (pool === undefined) {
51
+ pool = { active: 0, waiters: [] }
52
+ pools.set(key, pool)
53
+ }
54
+ return pool
55
+ }
56
+
57
+ const release = (key: string): void => {
58
+ const pool = pools.get(key)
59
+ if (pool === undefined) return
60
+ pool.active--
61
+ const next = pool.waiters.shift()
62
+ if (next) {
63
+ pool.active++
64
+ next()
65
+ // Drop idle pools so a long-lived semaphore does not accumulate one entry
66
+ // per key ever seen.
67
+ } else if (pool.active === 0 && pool.waiters.length === 0) {
68
+ pools.delete(key)
69
+ }
70
+ }
71
+
72
+ const acquire = (key: string, signal?: AbortSignal): Promise<void> => {
73
+ if (signal?.aborted) return Promise.reject(new SemaphoreAbortedError())
74
+ const pool = poolFor(key)
75
+ if (pool.active < concurrency) {
76
+ pool.active++
77
+ return Promise.resolve()
78
+ }
79
+ return new Promise<void>((resolve, reject) => {
80
+ let settled = false
81
+ const grant: Waiter = () => {
82
+ if (settled) {
83
+ // Granted after we already aborted: hand the freed slot to the next
84
+ // waiter so an aborted grant never leaks a permanently-held slot.
85
+ release(key)
86
+ return
87
+ }
88
+ settled = true
89
+ signal?.removeEventListener('abort', onAbort)
90
+ resolve()
91
+ }
92
+ const onAbort = (): void => {
93
+ if (settled) return
94
+ settled = true
95
+ const idx = pool.waiters.indexOf(grant)
96
+ if (idx >= 0) pool.waiters.splice(idx, 1)
97
+ reject(new SemaphoreAbortedError())
98
+ }
99
+ pool.waiters.push(grant)
100
+ signal?.addEventListener('abort', onAbort, { once: true })
101
+ })
102
+ }
103
+
104
+ return {
105
+ async run<T>(key: string, work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
106
+ await acquire(key, signal)
107
+ try {
108
+ return await work()
109
+ } finally {
110
+ release(key)
111
+ }
112
+ },
113
+ }
114
+ }
@@ -0,0 +1,82 @@
1
+ // Retry-with-backoff for search-engine calls that hit a transient rate-limit
2
+ // or CAPTCHA wall.
3
+ //
4
+ // Empirically, lite.duckduckgo.com does NOT recover in milliseconds once it
5
+ // starts gating: a tripped source IP stays boxed for minutes, and the gate
6
+ // surfaces as a CAPTCHA page (parsed as DdgCaptchaError) rather than a clean
7
+ // 429. So the backoff here is deliberately generous (seconds, growing) — a
8
+ // tight millisecond retry would just burn the remaining budget and confirm the
9
+ // box. The concurrency cap (keyed-semaphore.ts) is the real preventer; this is
10
+ // the second line of defense for a request that still raced into a gate.
11
+ //
12
+ // `shouldRetry` decides which errors are worth retrying — only transient
13
+ // rate-limit/CAPTCHA signals, never a parse error or a hard network failure.
14
+
15
+ export type SearchRetryOptions = {
16
+ attempts?: number
17
+ baseDelayMs?: number
18
+ maxDelayMs?: number
19
+ shouldRetry: (error: unknown) => boolean
20
+ signal?: AbortSignal
21
+ // Injectable sleep so tests can run without real timers.
22
+ sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
23
+ }
24
+
25
+ export const DEFAULT_SEARCH_RETRY_ATTEMPTS = 3
26
+ export const DEFAULT_SEARCH_RETRY_BASE_DELAY_MS = 2_000
27
+ export const DEFAULT_SEARCH_RETRY_MAX_DELAY_MS = 15_000
28
+
29
+ export async function withSearchRetry<T>(work: () => Promise<T>, options: SearchRetryOptions): Promise<T> {
30
+ const attempts = Math.max(1, Math.floor(options.attempts ?? DEFAULT_SEARCH_RETRY_ATTEMPTS))
31
+ const baseDelayMs = options.baseDelayMs ?? DEFAULT_SEARCH_RETRY_BASE_DELAY_MS
32
+ const maxDelayMs = options.maxDelayMs ?? DEFAULT_SEARCH_RETRY_MAX_DELAY_MS
33
+ const sleep = options.sleep ?? defaultSleep
34
+
35
+ let lastError: unknown
36
+ for (let attempt = 0; attempt < attempts; attempt++) {
37
+ if (options.signal?.aborted) throw new SearchRetryAbortedError()
38
+ try {
39
+ return await work()
40
+ } catch (error) {
41
+ lastError = error
42
+ const isLastAttempt = attempt === attempts - 1
43
+ if (isLastAttempt || !options.shouldRetry(error)) throw error
44
+ await sleep(backoffDelayMs(attempt, baseDelayMs, maxDelayMs), options.signal)
45
+ }
46
+ }
47
+ throw lastError
48
+ }
49
+
50
+ export class SearchRetryAbortedError extends Error {
51
+ constructor() {
52
+ super('Search retry aborted.')
53
+ this.name = 'SearchRetryAbortedError'
54
+ }
55
+ }
56
+
57
+ // Exponential backoff with full jitter (AWS "Exponential Backoff And Jitter").
58
+ // Full jitter — random in [0, capped] — decorrelates concurrent retriers so a
59
+ // burst that all tripped the gate together does not re-collide on the same
60
+ // wake-up, which would just re-trip the box.
61
+ export function backoffDelayMs(attempt: number, baseDelayMs: number, maxDelayMs: number): number {
62
+ const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt)
63
+ return Math.floor(Math.random() * capped)
64
+ }
65
+
66
+ function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
67
+ return new Promise((resolve, reject) => {
68
+ if (signal?.aborted) {
69
+ reject(new SearchRetryAbortedError())
70
+ return
71
+ }
72
+ const timer = setTimeout(() => {
73
+ signal?.removeEventListener('abort', onAbort)
74
+ resolve()
75
+ }, ms)
76
+ const onAbort = (): void => {
77
+ clearTimeout(timer)
78
+ reject(new SearchRetryAbortedError())
79
+ }
80
+ signal?.addEventListener('abort', onAbort, { once: true })
81
+ })
82
+ }
@@ -77,6 +77,10 @@ End every response with this exact structure:
77
77
  - If the question requires EXTERNAL/web information (docs, library reference, web search, fetching a URL), say so explicitly and tell the caller to spawn \`scout\` instead. Do not try to answer external questions from memory.
78
78
  - If you cannot find what was asked, say so explicitly with what you DID find and what surfaces you searched.`
79
79
 
80
+ // `profile` is dropped, not passed through: explorer is a fast-tier specialist, so
81
+ // a parent must not bump it off `fast` via a per-spawn `profile` override (which the
82
+ // `spawn_subagent` tool injects into the payload and `profileFromPayload` would
83
+ // otherwise honor). Other fields still pass through untouched.
80
84
  export const explorerPayloadSchema = z
81
85
  .object({
82
86
  requestId: z.string().optional(),
@@ -84,6 +88,7 @@ export const explorerPayloadSchema = z
84
88
  description: z.string().optional(),
85
89
  })
86
90
  .passthrough()
91
+ .transform(({ profile: _profile, ...rest }) => rest)
87
92
 
88
93
  export type ExplorerPayload = z.infer<typeof explorerPayloadSchema>
89
94
 
@@ -135,7 +135,7 @@ A `[dreaming] citation-superset violation: …` warning logs the dropped ids and
135
135
  - **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards. A `fragment` event carries optional **situational provenance** for "who said what, where, and when": `who` (display name/handle of the attributed speaker, LLM-supplied per-fragment by `memory-logger` only when one transcript speaker clearly owns the evidence), `where` (`{ adapter, workspace, workspaceName?, chat, chatName?, thread }` — runtime-stamped from the session origin in the append tool, channel origins only), and `when` (reuses the existing `ts`). Both are optional, so legacy fragments and non-channel (TUI) origins parse with them absent. `who`/`where` are deliberately NOT in `fragmentContentHash` (dedup stays content-identity) and NOT in `fragmentEmbeddableText` (provenance is retrieval metadata, not embedded — it must not burn the 512-token budget or let same-room/same-person dominate recall). **Secret-scanning covers provenance too**: `who` (LLM-supplied) clears the same `detectSecrets` guard as `topic`/`body` and a credential-shaped value is refused with the retryable error; the origin-derived `where` names (`workspaceName`/`chatName`) are external channel data the agent can't rewrite, so a credential-shaped name is silently dropped (raw id kept) rather than wedging the logger. Raw ids are platform-issued identifiers, not free text, so they are not scanned. `where` is runtime-stamped rather than LLM-supplied because the channel is stable for a whole logger run; `who` is per-fragment because a single run spans many speakers and `origin.lastInboundAuthorId` is only the spawn-time one — auto-stamping it would misattribute fragments about earlier speakers. Surfaced to the agent (not embedded) via `memory_search` (`StreamMatch.who/when/where`), `hybridSearch` (`HybridSearchResult.who/when/where` on self-resolved undreamed fragments), and the per-turn retrieval render (`renderProvenanceLine` → `_Jisoo in #incidents on 2026-06-24_`).
136
136
  - **`memory/MEMORY.md.pre-shard.bak`** — legacy pre-shard backup left by older TypeClaw versions. Safe to delete after verifying.
137
137
  - **`memory/skills/<name>/SKILL.md`** — muscle memory (Form A). Skills the dreaming subagent distills from repeated procedures. Auto-loaded as first-class skills. CLI/plugin suggestions (Forms B and C) are recorded as topic shards instead — see [Muscle memory](#muscle-memory-three-forms).
138
- - **`memory/references/<slug>.md`** — verbatim reference artifacts (gated behind `memory.references.enabled`). Written by `store_reference`. When vector is enabled, a freshly stored reference is embedded into the vector index immediately via the `store_reference` on-write hook (`vector/reference-index-on-write.ts`), mirroring the stream-fragment on-write hook — so it is vector-retrievable within the same container uptime instead of only after the next startup index build. Chunks are derived by the same `referencePassagesForOne` the startup build uses, and re-storing a shorter body prunes the stale higher-index chunk rows.
138
+ - **`memory/references/<slug>.md`** — verbatim reference artifacts. Written by `store_reference`, a `memory-logger` custom tool that is always registered (there is no `references.enabled` config gate — references are unconditionally available; they simply stay empty until the `memory-logger` chooses to store one). A fragment may cite a stored reference via `append`'s `references: ['<slug>']`, but the append tool validates each slug against the references that actually exist on disk and silently drops the rest (`resolveValidReferences`), so a hallucinated slug never lands a dangling citation in the stream. When vector is enabled, a freshly stored reference is embedded into the vector index immediately via the `store_reference` on-write hook (`vector/reference-index-on-write.ts`), mirroring the stream-fragment on-write hook — so it is vector-retrievable within the same container uptime instead of only after the next startup index build. Chunks are derived by the same `referencePassagesForOne` the startup build uses, and re-storing a shorter body prunes the stale higher-index chunk rows.
139
139
  - **`memory/.dreaming-state.json`** — per-day dreamed-id sets.
140
140
  - **`memory/.retrieval-cache/<sessionId>.md`** — ephemeral retrieval summaries. Written by `memory-retrieval`, read by `loadMemory` on the next prompt of the same session, unlinked on `session.end`.
141
141
 
@@ -145,7 +145,7 @@ The plugin emits structured `[plugin:memory]` log lines (no separate metrics inf
145
145
 
146
146
  - **`[memory-logger] <session> done fragments_written=N elapsed_ms=…`** — how many fragments a logger run captured (delta of fragment events in today's stream).
147
147
  - **`[dreaming] done topics_created=N topics_removed=N superseded_new=N fragments_dropped=N over_budget=N elapsed_ms=…`** — consolidation activity per run: new/removed topic shards (by snapshot path diff), net citations moved into `superseded:`, fragments GC'd, and `over_budget` (the count of topic shards whose embeddable text exceeds the model token budget — see [Embedding token budget](#embedding-token-budget)). `topics_created` + reinforcement is the "is memory getting sharper" signal; `superseded_new` is contradiction-edit volume; a persistently non-zero `over_budget` means the subagent isn't compacting the flagged shards. Derived by `computeDreamingMetrics` from the pre/post shard snapshots.
148
- - **`[vector-retrieval] mode=index topic_results=N stream_results=N reference_results=N elapsed_ms=… [suppressed=1]`** (or `mode=direct topics=N`) — per-turn retrieval breakdown. `stream_results` counts undreamed-fragment hits that self-resolved (no citing topic yet) — the freshness-window usage signal that informs whether the undreamed surface earns its keep. `reference_results` counts verbatim-reference hits (only non-zero when `references.enabled`), broken out from `stream_results` so the two surfaces are distinguishable. `elapsed_ms` times the full `hybridSearch` (embed + cosine scan + keyword lane + RRF fusion) — the on-critical-path retrieval cost. `suppressed=1` appears when the query matched nothing after the relevance gate, so an empty memory block is distinguishable from a missing one.
148
+ - **`[vector-retrieval] mode=index topic_results=N stream_results=N reference_results=N elapsed_ms=… [suppressed=1]`** (or `mode=direct topics=N`) — per-turn retrieval breakdown. `stream_results` counts undreamed-fragment hits that self-resolved (no citing topic yet) — the freshness-window usage signal that informs whether the undreamed surface earns its keep. `reference_results` counts verbatim-reference hits (non-zero once the `memory-logger` has stored at least one reference and vector is enabled), broken out from `stream_results` so the two surfaces are distinguishable. `elapsed_ms` times the full `hybridSearch` (embed + cosine scan + keyword lane + RRF fusion) — the on-critical-path retrieval cost. `suppressed=1` appears when the query matched nothing after the relevance gate, so an empty memory block is distinguishable from a missing one.
149
149
 
150
150
  These are intentionally verbose for now so behavior is observable in logs; trim once the useful subset is known.
151
151
 
@@ -21,9 +21,17 @@ export type FragmentsAppendedHook = (fragments: FragmentEvent[], context: Fragme
21
21
  // value) because the same factory builds tools whose origin is only known later.
22
22
  export type OriginProvider = () => SessionOrigin | undefined
23
23
 
24
+ // Returns the set of reference slugs the agent is allowed to cite from
25
+ // `references[]`: every reference that exists on disk (a `store_reference` call
26
+ // writes the file synchronously before returning the slug, so a same-run store
27
+ // is already on disk by append time). Lets the append tool strip hallucinated
28
+ // slugs the model invents without ever calling `store_reference`.
29
+ export type ReferenceSlugResolver = (agentDir: string) => Promise<Iterable<string>>
30
+
24
31
  export type CreateAppendToolOptions = {
25
32
  onFragmentsAppended?: FragmentsAppendedHook
26
33
  originProvider?: OriginProvider
34
+ referenceSlugResolver?: ReferenceSlugResolver
27
35
  }
28
36
 
29
37
  // Stamped fields are the stable channel coordinates only. Author identity is
@@ -57,10 +65,10 @@ function redactIfSecret(name: string | undefined): string | undefined {
57
65
  }
58
66
 
59
67
  export function createAppendTool(options: CreateAppendToolOptions = {}) {
60
- const { onFragmentsAppended, originProvider } = options
68
+ const { onFragmentsAppended, originProvider, referenceSlugResolver } = options
61
69
  return defineTool({
62
70
  description:
63
- "Append a memory fragment to today's JSONL daily stream and advance the watermark. The runtime serializes your call into a JSON line and chooses the filename — do not emit raw JSON and do not pass a path. `topic`/`body` are the fragment's substance; `source` is the parent session id; `entry` is the transcript-entry-id this fragment anchors to; `latestEntryId` is the latest transcript-entry-id you evaluated in this run (advances the watermark, may equal `entry` or be later). `who` is the display name/handle of the person the fragment's evidence is attributable to — set it ONLY when one transcript speaker clearly owns the evidence; omit it when the fact is the user's own, spans multiple speakers, or is not attributable. The channel/room/platform (`where`) is stamped automatically from the session origin — do not pass it and do not restate it in the body. Refuses content with recognized credential patterns and refuses byte-equivalent topic+body within the same daily stream.",
71
+ "Append a memory fragment to today's JSONL daily stream and advance the watermark. The runtime serializes your call into a JSON line and chooses the filename — do not emit raw JSON and do not pass a path. `topic`/`body` are the fragment's substance; `source` is the parent session id; `entry` is the transcript-entry-id this fragment anchors to; `latestEntryId` is the latest transcript-entry-id you evaluated in this run (advances the watermark, may equal `entry` or be later). `references` may ONLY contain slugs returned by `store_reference` (it returns the slug it wrote) — never topic ids, PR names, stream paths, or invented labels; unknown slugs are dropped. `who` is the display name/handle of the person the fragment's evidence is attributable to — set it ONLY when one transcript speaker clearly owns the evidence; omit it when the fact is the user's own, spans multiple speakers, or is not attributable. The channel/room/platform (`where`) is stamped automatically from the session origin — do not pass it and do not restate it in the body. Refuses content with recognized credential patterns and refuses byte-equivalent topic+body within the same daily stream.",
64
72
  parameters: z.object({
65
73
  topic: z.string().min(1),
66
74
  body: z.string().min(1),
@@ -104,8 +112,9 @@ export function createAppendTool(options: CreateAppendToolOptions = {}) {
104
112
  topic,
105
113
  body,
106
114
  }
107
- if (references !== undefined && references.length > 0) {
108
- fragment.references = references
115
+ const validReferences = await resolveValidReferences(references, referenceSlugResolver, ctx)
116
+ if (validReferences.length > 0) {
117
+ fragment.references = validReferences
109
118
  }
110
119
  if (who !== undefined) fragment.who = who
111
120
  if (where !== undefined) fragment.where = where
@@ -173,6 +182,35 @@ function dailyStreamPath(agentDir: string): string {
173
182
  return streamFilePath(agentDir, formatLocalDate())
174
183
  }
175
184
 
185
+ // The model treats `references[]` as a free-text related-id field, citing empty
186
+ // strings, stream paths, and slugs for references it never stored. Every path
187
+ // first normalizes: trim, drop blank/whitespace-only entries, and de-duplicate
188
+ // — an empty or repeated citation is never meaningful regardless of wiring.
189
+ // With a resolver, only slugs backed by a real reference file then survive; the
190
+ // rest are dropped and logged so dangling citations never reach the stream.
191
+ // Without one (the standalone `appendTool` export, no reference subsystem
192
+ // wired) the normalized slugs pass through.
193
+ async function resolveValidReferences(
194
+ references: string[] | undefined,
195
+ resolver: ReferenceSlugResolver | undefined,
196
+ ctx: { agentDir: string; logger?: { warn(message: string): void } },
197
+ ): Promise<string[]> {
198
+ if (references === undefined || references.length === 0) return []
199
+ const requested = [...new Set(references.map((slug) => slug.trim()).filter((slug) => slug.length > 0))]
200
+ if (resolver === undefined) return requested
201
+
202
+ const known = new Set(await resolver(ctx.agentDir))
203
+ const valid = requested.filter((slug) => known.has(slug))
204
+ const dropped = requested.filter((slug) => !known.has(slug))
205
+ if (dropped.length > 0) {
206
+ ctx.logger?.warn(
207
+ `[memory] dropped ${dropped.length} unknown reference slug(s) from fragment: ${dropped.join(', ')}. ` +
208
+ `references[] may only cite slugs returned by store_reference.`,
209
+ )
210
+ }
211
+ return valid
212
+ }
213
+
176
214
  function assertNoSecrets(parts: ReadonlyArray<string | undefined>): void {
177
215
  const content = parts.filter((part): part is string => part !== undefined).join('\n')
178
216
  const secrets = detectSecrets(content)
@@ -7,6 +7,7 @@ import { formatLocalDate } from '@/shared'
7
7
  import { advanceWatermarkTool, createAppendTool, type FragmentsAppendedHook } from './append-tool'
8
8
  import { findEntryTool } from './find-entry-tool'
9
9
  import { streamFilePath, streamsDir } from './paths'
10
+ import { listReferenceSlugs } from './references/load-references'
10
11
  import { createStoreReferenceTool, type ReferenceStoredHook } from './references/store-reference-tool'
11
12
  import { readEvents } from './stream-io'
12
13
  import { readLatestWatermark } from './watermark'
@@ -146,9 +147,11 @@ Skip these anti-patterns:
146
147
 
147
148
  # Verbatim references (store_reference tool)
148
149
 
149
- When the user explicitly asks to remember a verbatim artifact — SQL, code, a runbook, pasted spec — call \`store_reference({ title, body, origin: 'episode', tags: [] })\` with the byte-for-byte body. Do not distill or summarize it. The tool returns a slug; include it in \`append\` as \`references: ['<slug>']\` when writing the session fragment.
150
+ Store a verbatim artifact whenever its memory value depends on the EXACT text — SQL, code blocks, runbooks, pasted specs, config snippets, API payloads, review comments, or command output the user will want reproduced byte-for-byte later. This is not limited to "please remember this": if you are about to write a fragment that summarizes such an artifact, store the artifact too so the exact text survives. Call \`store_reference({ title, body, origin: 'episode', tags: [] })\` with the byte-for-byte body. Do not distill or summarize the body.
150
151
 
151
- If the reference is the only durable content, still write a fragment (topic "verbatim reference stored") naming what was stored and citing the reference, so the reference is linked into the stream.
152
+ \`store_reference\` returns a slug (the file it wrote under \`memory/references/\`). The ONLY valid contents of \`append\`'s \`references\` field are slugs you received back from \`store_reference\` in THIS run. Never put a topic id, PR name/number, stream path, URL, or any invented label in \`references\` — those are not references and will be silently dropped. If you did not call \`store_reference\`, omit \`references\` entirely. To cross-link a related topic, name it in the body prose instead.
153
+
154
+ If a stored reference is the only durable content, still write a fragment (topic "verbatim reference stored") naming what was stored and citing the returned slug, so the reference is linked into the stream.
152
155
 
153
156
  References are for artifacts whose exact text matters. A distilled memory fragment should name what the artifact is, who/what it applies to, and why it was retained, while the reference body holds the verbatim material. Do not paste large reference bodies into fragment text.
154
157
 
@@ -179,7 +182,7 @@ Recurrence is not duplication. A durable preference, pattern, workaround, or com
179
182
 
180
183
  # Fragment format
181
184
 
182
- Call \`append\` with \`{topic, body, source, entry, latestEntryId}\` or \`{topic, body, source, entry, latestEntryId, references}\`. The runtime serializes your call into the daily stream; you never write raw JSON. \`source\` is the parent session id. \`topic\` is a short noun phrase. \`entry\` is the specific transcript-entry-id that anchors this fragment's evidence. Each fragment carries its own entry id; do not stamp every fragment with the same latest evaluated id. \`latestEntryId\` is the latest entry evaluated in this run and advances the watermark. \`references\` is optional slugs from \`store_reference\`.
185
+ Call \`append\` with \`{topic, body, source, entry, latestEntryId}\` or \`{topic, body, source, entry, latestEntryId, references}\`. The runtime serializes your call into the daily stream; you never write raw JSON. \`source\` is the parent session id. \`topic\` is a short noun phrase. \`entry\` is the specific transcript-entry-id that anchors this fragment's evidence. Each fragment carries its own entry id; do not stamp every fragment with the same latest evaluated id. \`latestEntryId\` is the latest entry evaluated in this run and advances the watermark. \`references\` is optional and may ONLY contain slugs that \`store_reference\` returned to you in this run; anything else (topic ids, PR names, stream paths, invented labels) is dropped — omit the field if you stored nothing.
183
186
 
184
187
  **Situational provenance (\`who\` / \`where\`).** Memory is sharper when it remembers who said something and where. Two fields capture this:
185
188
 
@@ -297,6 +300,7 @@ export function createMemoryLoggerSubagent(
297
300
  const appendTool = createAppendTool({
298
301
  onFragmentsAppended: options.onFragmentsAppended,
299
302
  originProvider: () => currentOrigin,
303
+ referenceSlugResolver: (agentDir) => listReferenceSlugs(agentDir),
300
304
  })
301
305
  const storeReferenceTool = createStoreReferenceTool(options.onReferenceStored)
302
306
  const customTools = [findEntryTool, appendTool, storeReferenceTool, advanceWatermarkTool]
@@ -79,7 +79,9 @@ Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to
79
79
 
80
80
  You run on a deliberately expensive model. Reading a sprawling file tree, a giant diff, or a pile of vendor docs into YOUR context burns that budget on grunt work. When a slice of the job is bulky-but-mechanical — "summarize what these 40 files do", "extract the public API of this module", "gather the relevant passages from this 2,000-line diff" — hand it to a cheaper worker with \`spawn_subagent\` and review the distilled result instead of the raw bulk.
81
81
 
82
- - Spawn read-only/research workers for context-heavy gathering, not for forming the verdict. The findings and the \`<review>\` block are YOURS — never delegate the judgment.
82
+ This is not a last resort — it is your DEFAULT for any non-trivial target, and it makes the review FASTER, not just leaner. Reach for \`scout\` and \`explorer\` first: \`explorer\` maps unfamiliar code and finds where things live, \`scout\` gathers focused facts from a known area. Decompose the target into independent gathering tasks and fan them out IN PARALLEL — emit several \`spawn_subagent\` calls in a SINGLE turn (they run concurrently and return together) rather than reading each slice yourself, one after another, into your own context. A wall-clock-faster review on a fresh, uncluttered context is the win; serial self-reading is the slow path you are explicitly steered away from.
83
+
84
+ - Spawn read-only/research workers (\`scout\`, \`explorer\`) for context-heavy gathering, not for forming the verdict. The findings and the \`<review>\` block are YOURS — never delegate the judgment.
83
85
  - Each delegated task must be self-contained: the worker does not see this conversation or the target. Put everything it needs in the prompt.
84
86
  - The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
85
87
  - \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. To gather in parallel, either emit all the independent \`spawn_subagent\` calls (sync, the default) in a SINGLE turn so they run concurrently and return together, or spawn them with \`run_in_background=true\` and fold each result in as its \`<system-reminder>\` arrives (your session stays alive until every child reports back). Either way, fold the results into your single review pass before you finish.
@@ -68,6 +68,10 @@ End every response with this exact structure:
68
68
  - If the question requires LOCAL information (codebase, files in /agent/, git history, memory), say so explicitly and tell the caller to spawn \`explorer\` instead.
69
69
  - If you cannot find what was asked, say so explicitly with what queries you tried and what you DID find.`
70
70
 
71
+ // `profile` is dropped, not passed through: scout is a fast-tier specialist, so a
72
+ // parent must not bump it off `fast` via a per-spawn `profile` override (which the
73
+ // `spawn_subagent` tool injects into the payload and `profileFromPayload` would
74
+ // otherwise honor). Other fields still pass through untouched.
71
75
  export const scoutPayloadSchema = z
72
76
  .object({
73
77
  requestId: z.string().optional(),
@@ -75,6 +79,7 @@ export const scoutPayloadSchema = z
75
79
  description: z.string().optional(),
76
80
  })
77
81
  .passthrough()
82
+ .transform(({ profile: _profile, ...rest }) => rest)
78
83
 
79
84
  export type ScoutPayload = z.infer<typeof scoutPayloadSchema>
80
85
 
@@ -13,6 +13,24 @@ export type OutboundEndpointKind =
13
13
  | 'issue-reaction'
14
14
  | 'pr-review-comment-reaction'
15
15
 
16
+ // The required-permissions checklist shown verbatim during interactive GitHub
17
+ // channel setup (both `typeclaw init` and `typeclaw channel add github`). Kept
18
+ // here — the single owner of GitHub permission copy — so the init and
19
+ // channel-add flows can't drift apart (they did once: Actions was added to one
20
+ // and not the other). The labels mirror github.com's UI strings so a user can
21
+ // grep their settings page for the exact text. `includeWebhookNote` appends the
22
+ // "TypeClaw will create and manage the repository webhooks for you" reassurance,
23
+ // shown only on the first-setup prompts (not the rotate/switch prompts).
24
+ export function githubRequiredPermissionsNote(includeWebhookNote: boolean): string {
25
+ const webhooks = includeWebhookNote
26
+ ? 'Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).'
27
+ : 'Webhooks read/write.'
28
+ return [
29
+ 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
30
+ `Actions read/write, Metadata read, and ${webhooks}`,
31
+ ].join('\n')
32
+ }
33
+
16
34
  // Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
17
35
  // Returns the status code when it matches the two shapes GitHub emits for
18
36
  // missing access on the list-hooks endpoint:
@@ -4,6 +4,7 @@ import { cancel, confirm, intro, isCancel, log, note, password, select, spinner,
4
4
  import { defineCommand } from 'citty'
5
5
  import QRCode from 'qrcode'
6
6
 
7
+ import { githubRequiredPermissionsNote } from '@/channels/adapters/github/permission-guidance'
7
8
  import { config } from '@/config'
8
9
  import {
9
10
  listChannels,
@@ -1039,8 +1040,7 @@ async function promptGithubCredentials(cwd: string): Promise<{
1039
1040
  note(
1040
1041
  [
1041
1042
  'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
1042
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1043
- 'Metadata read, and Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).',
1043
+ githubRequiredPermissionsNote(true),
1044
1044
  ].join('\n'),
1045
1045
  'Get GitHub credentials',
1046
1046
  )
@@ -1196,19 +1196,16 @@ async function promptGithubAuthUpdate(currentType: 'pat' | 'app'): Promise<Githu
1196
1196
  if (nextType === 'pat') {
1197
1197
  if (action === 'rotate') {
1198
1198
  note(
1199
- [
1200
- 'Rotate at https://github.com/settings/personal-access-tokens.',
1201
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1202
- 'Metadata read, and Webhooks read/write.',
1203
- ].join('\n'),
1199
+ ['Rotate at https://github.com/settings/personal-access-tokens.', githubRequiredPermissionsNote(false)].join(
1200
+ '\n',
1201
+ ),
1204
1202
  'Rotate the GitHub PAT',
1205
1203
  )
1206
1204
  } else {
1207
1205
  note(
1208
1206
  [
1209
1207
  'Create a fine-grained PAT at https://github.com/settings/personal-access-tokens.',
1210
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1211
- 'Metadata read, and Webhooks read/write.',
1208
+ githubRequiredPermissionsNote(false),
1212
1209
  ].join('\n'),
1213
1210
  'Switch to GitHub PAT auth',
1214
1211
  )
@@ -1236,8 +1233,7 @@ async function promptGithubAuthUpdate(currentType: 'pat' | 'app'): Promise<Githu
1236
1233
  note(
1237
1234
  [
1238
1235
  'Create a GitHub App at https://github.com/settings/apps/new and install it on your repositories.',
1239
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1240
- 'Metadata read, and Webhooks read/write.',
1236
+ githubRequiredPermissionsNote(false),
1241
1237
  'Then collect the App ID, generate a private key (.pem), and grab the Installation ID from the URL',
1242
1238
  'of the installation page (https://github.com/settings/installations/<installation-id>).',
1243
1239
  ].join('\n'),
package/src/cli/init.ts CHANGED
@@ -15,6 +15,7 @@ import {
15
15
  } from '@clack/prompts'
16
16
  import { defineCommand } from 'citty'
17
17
 
18
+ import { githubRequiredPermissionsNote } from '@/channels/adapters/github/permission-guidance'
18
19
  import {
19
20
  KNOWN_PROVIDER_VENDORS,
20
21
  KNOWN_PROVIDERS,
@@ -1666,8 +1667,7 @@ async function runGithubFlow(cwd: string): Promise<StepResult<CollectedInputs['c
1666
1667
  note(
1667
1668
  [
1668
1669
  'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
1669
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1670
- 'Metadata read, and Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).',
1670
+ githubRequiredPermissionsNote(true),
1671
1671
  ].join('\n'),
1672
1672
  'Get GitHub credentials',
1673
1673
  )
@@ -1,4 +1,4 @@
1
- import { proxyContainerCommand } from './container-command-client'
1
+ import { proxyContainerCommand, type ContainerProxyOptions } from './container-command-client'
2
2
  import { parseArgs, runHostCommand } from './host-command-runner'
3
3
  import { renderCommandHelp } from './plugin-command-help'
4
4
  import { discoverCommands } from './plugin-commands'
@@ -16,6 +16,11 @@ export type DispatchOptions = {
16
16
  stdout?: WritableStream<Uint8Array>
17
17
  stderr?: WritableStream<Uint8Array>
18
18
  signal?: AbortSignal
19
+ // Test seam: override container-URL resolution so unit tests exercise the
20
+ // container dispatch path without spawning a real `docker inspect` (slow and
21
+ // flaky on Windows CI). Unset in production: proxyContainerCommand falls back
22
+ // to the live docker probe.
23
+ resolveContainerUrl?: ContainerProxyOptions['resolveUrl']
19
24
  }
20
25
 
21
26
  export async function dispatchPluginCommand(opts: DispatchOptions): Promise<PluginCommandDispatchOutcome> {
@@ -62,6 +67,7 @@ export async function dispatchPluginCommand(opts: DispatchOptions): Promise<Plug
62
67
  stdout,
63
68
  stderr,
64
69
  abortSignal: signal,
70
+ resolveUrl: opts.resolveContainerUrl,
65
71
  })
66
72
  if (!containerResult.ok) {
67
73
  return { kind: 'error', exitCode: containerResult.exitCode, message: containerResult.message }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-channel-github
3
- 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.
3
+ 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`. ALWAYS settle PR authorship first (triage #0): on a PR **you** opened you are the CONTRIBUTOR/author, not its reviewer — "address the review" / "리뷰 반영" / "fix the feedback" / a `CHANGES_REQUESTED` on your own PR means change the code, push, and reply, NOT spawn the reviewer or post a formal verdict; you never review your own PR. The reviewer persona is for other people's PRs only. 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.
4
4
  ---
5
5
 
6
6
  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.
@@ -18,33 +18,79 @@ A successful `channel_reply` ends your turn by default — the runtime stops the
18
18
 
19
19
  Before you pick an action, classify the inbound. Skipping this step is how a PR ends up with a "looks good" comment but no approval: the model pattern-matches on the prose ("they fixed it → resolve the thread") and never asks whether it owes the PR a formal review. Answer these in order; the **first** that matches decides your path. Do not skip ahead.
20
20
 
21
- 1. **Is this a PR, and do I have an unresolved blocking obligation on it?** On any `pr:N` inbound, before anything else, check whether you owe this PR a verdict you have not yet landed. Check **both** signals below — checking only formal review state misses the very failure this gate exists to catch, because a prior block may never have become formal state:
21
+ 0. **Whose PR is this — mine or someone else's?** On any `pr:N` inbound, **before** you ask anything about reviewing, settle authorship. Fetch the author and compare it to your own login (`<your-login>`, your GitHub App login — typically `name[bot]`):
22
+
23
+ ```sh
24
+ gh pr view <N> --repo owner/repo --json author --jq '.author.login'
25
+ ```
26
+
27
+ - **The PR author is you (`<your-login>`).** You are the **contributor/author** on this PR, not its reviewer. Feedback on it — a review, a "리뷰 반영 부탁드려요" / "address the review" / "please apply the feedback" / "fixed?" comment, a `CHANGES_REQUESTED` someone else left — is yours to **address as the author**: read it, change the code, push, and reply. Go to the **contributor flow** ("When the PR is yours"). **You never review your own PR**, and you never spawn the `reviewer` subagent on it — GitHub does not even let an author formally review their own PR, so an attempt produces a self-addressed "review" comment, which is the exact persona-confusion bug to avoid. Gates 1–2 below (review obligations / review requests) describe the _reviewer_ persona and **do not apply when the PR is yours** — skip straight to the contributor flow.
28
+ - **The PR author is someone else.** You may be its reviewer. Continue to gate 1.
29
+
30
+ This gate is first because everything after it assumes the reviewer persona. "Address the review" sounds identical whether you wrote the PR or someone else did; only the author check disambiguates, and getting it wrong is what makes the agent review its own work.
31
+
32
+ 1. **(Someone else's PR.) Do I have an unresolved blocking obligation on it?** On any `pr:N` inbound, before anything else, check whether you owe this PR a verdict you have not yet landed. Check **both** signals below — checking only formal review state misses the very failure this gate exists to catch, because a prior block may never have become formal state:
22
33
  - **Formal review state.** Run the step-1 re-review query in the PR review flow (`gh api --paginate --slurp /repos/owner/repo/pulls/<N>/reviews --jq '…'` filtered to `{CHANGES_REQUESTED, APPROVED}`). If your latest **blocking decision** is `CHANGES_REQUESTED`, you have a live sticky block.
23
34
  - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`. **A courtesy acknowledgement is not a retraction.** A reply you posted like "nice, that closes the hole" / "thanks, looks good" / "✅" does **not** supersede or retract a blocker you raised — it is a chat ack, not a verdict, and it carries no review state. The blocker stays binding until you land a **formal** `APPROVE`/`REQUEST_CHANGES` (or dismiss your prior review). So when an earlier "✅ thanks" of yours is the only thing between your blocker and the author's address-comment, the blocker is **still live** and this inbound is a re-review — do not let your own ack downgrade it.
24
35
 
25
36
  If **either** signal shows an unresolved blocker you raised, this inbound is a **re-review** — go to the **PR review flow** regardless of how it is phrased. An author commenting "fixed both issues" / "addressed your feedback" / "pushed a fix" is a re-review trigger, **not** a thread-resolve trigger. A re-review is closed by re-deciding the verdict and landing a **formal** review via `POST /pulls/<N>/reviews`: `APPROVE` clears a sticky `CHANGES_REQUESTED`; a comment or a flat reply clears neither a formal block nor a flat-comment blocker — it just strands the verdict again, which is the original bug.
26
37
 
27
- 2. **Am I being asked to review (first-time)?** Explicit `review_requested` inbound, or a human asking in plain language ("review this", "take a look at #N"). → **PR review flow** (see "When you are being asked to review").
38
+ 2. **(Someone else's PR.) Am I being asked to review (first-time)?** Explicit `review_requested` inbound, or a human asking in plain language ("review this", "take a look at #N"). → **PR review flow** (see "When you are being asked to review").
28
39
 
29
40
  3. **Is this a reply inside an inline review thread I authored** (`pr:N` with `thread` set, on a thread whose root comment is mine)? → verify the fix at head SHA and **resolve the thread** (see "Resolving review threads you authored"). `resolve_review_thread` only works when `thread` is set on the origin; if there is **no** `thread`, this branch does not apply — do not attempt it, fall through to the table below.
30
41
 
31
42
  4. **None of the above** → use the routing table below.
32
43
 
33
- > The decisive question is **#1**. A blocking verdict you owe a PR is never discharged by a `channel_reply` or an `issue_comment` — neither carries review state, and neither clears a sticky `CHANGES_REQUESTED`. This applies to an **unresolved blocking obligation** (a live `CHANGES_REQUESTED`, or an unretracted blocker you raised in a flat comment), not to a stale `APPROVED` or a past non-blocking comment — those impose no closeout duty. When you do owe a block, the close-out is always a formal review via `POST /pulls/<N>/reviews`.
44
+ > The decisive questions are **#0 then #1**. First settle authorship (#0): if the PR is yours you are the contributor and gates 1–2 do not apply — address the feedback, never review your own work. Only on someone else's PR does #1 govern: a blocking verdict you owe a PR is never discharged by a `channel_reply` or an `issue_comment` — neither carries review state, and neither clears a sticky `CHANGES_REQUESTED`. This applies to an **unresolved blocking obligation** (a live `CHANGES_REQUESTED`, or an unretracted blocker you raised in a flat comment), not to a stale `APPROVED` or a past non-blocking comment — those impose no closeout duty. When you do owe a block, the close-out is always a formal review via `POST /pulls/<N>/reviews`.
34
45
 
35
46
  ## What to do, by inbound type
36
47
 
37
48
  Every GitHub inbound lands on a `chat` keyed by its subject: `issue:N`, `pr:N`, or `discussion:N`. **Run the triage above first.** Only if no triage branch matched do you pick an action from this table. The default action for anything addressed to you is a normal `channel_reply` in that thread; the **PR review flow** is the exception that requires delegation.
38
49
 
39
- | Inbound | Looks like | What to do |
40
- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
41
- | **New issue** (`issue:N`) | A freshly opened issue body. | Triage or answer it. `channel_reply` on `issue:N`. Open follow-up issues/PRs with `gh` if needed. |
42
- | **Issue comment** (`issue:N`) | A comment on an issue. | Reply in the issue thread with `channel_reply`. |
43
- | **PR conversation comment** (`pr:N`, no `thread`) | A comment on a PR's main conversation (GitHub models PR comments as issue comments). | Reply on the PR with `channel_reply`. **If the text asks you to review → go to the PR review flow.** |
44
- | **PR review-thread reply** (`pr:N`, `thread` set) | A reply on an existing inline review comment thread. | Stay in the thread: `channel_reply` with `thread` kept as-is. **If it addresses a comment you authored → verify and resolve the thread (below).** |
45
- | **A submitted review** (`pr:N`) | Someone submitted a formal review (approve / changes / comment) on a PR. | React if a response is warranted (answer a question, acknowledge changes). `channel_reply` on `pr:N`. |
46
- | **New discussion / discussion comment** (`discussion:N`) | A discussion thread or a comment in one. | Reply with `channel_reply` on `discussion:N`. |
47
- | **Review requested** (`pr:N`) | See "When you are being asked to review" below. | **PR review flow.** |
50
+ | Inbound | Looks like | What to do |
51
+ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | **New issue** (`issue:N`) | A freshly opened issue body. | Triage or answer it. `channel_reply` on `issue:N`. Open follow-up issues/PRs with `gh` if needed. |
53
+ | **Issue comment** (`issue:N`) | A comment on an issue. | Reply in the issue thread with `channel_reply`. |
54
+ | **PR conversation comment** (`pr:N`, no `thread`) | A comment on a PR's main conversation (GitHub models PR comments as issue comments). | Reply on the PR with `channel_reply`. **If the text asks you to review → go to the PR review flow.** |
55
+ | **PR review-thread reply** (`pr:N`, `thread` set) | A reply on an existing inline review comment thread. | Stay in the thread: `channel_reply` with `thread` kept as-is. **If it addresses a comment you authored → verify and resolve the thread (below).** |
56
+ | **A submitted review** (`pr:N`) | Someone submitted a formal review (approve / changes / comment) on a PR. | **If the PR is yours (triage #0) → contributor flow:** address the feedback, then reply. Otherwise react if a response is warranted. `channel_reply` on `pr:N`. |
57
+ | **Feedback on your own PR** (`pr:N`, author = `<your-login>`) | A review, a `CHANGES_REQUESTED`, or an "address the review / fixed?" comment on a PR **you** opened. | **Contributor flow** ("When the PR is yours"). Address the feedback as the author — never review or formally approve your own PR. |
58
+ | **New discussion / discussion comment** (`discussion:N`) | A discussion thread or a comment in one. | Reply with `channel_reply` on `discussion:N`. |
59
+ | **Review requested** (`pr:N`) | See "When you are being asked to review" below. | **PR review flow.** |
60
+
61
+ ### When the PR is yours — addressing review feedback (contributor)
62
+
63
+ Triage #0 sends you here whenever the `pr:N` was opened by **you** (`<your-login>`). On your own PR you wear the **author/contributor** hat, which is the mirror image of the reviewer flow below:
64
+
65
+ - **You do not review it.** Do **not** spawn the `reviewer` subagent, do **not** run `gh pr diff` to form a verdict, and do **not** call `POST /pulls/<N>/reviews` — GitHub forbids an author from formally reviewing their own PR, so the attempt degrades into a self-addressed "## Review … Concern 1/2" comment on your own work. That self-review is the precise bug this branch exists to prevent. The reviewer persona (spawn → `<review>` → formal verdict) is for **other people's** PRs only.
66
+ - **You address the feedback.** Read what the reviewer (human or bot) actually said. For each point: either change the code to fix it, or reply explaining why no change is needed. This is ordinary contributor work, not a review.
67
+
68
+ The flow:
69
+
70
+ 1. **Read the feedback at the current head.** Pull the review comments and any `CHANGES_REQUESTED` summary so you know exactly what is being asked.
71
+
72
+ ```sh
73
+ gh pr view <N> --repo owner/repo --json reviews,comments,headRefOid \
74
+ --jq '{reviews: [.reviews[] | {author: .author.login, state, body}], head: .headRefOid}'
75
+ gh api /repos/owner/repo/pulls/<N>/comments --jq '[.[] | {path, line, user: .user.login, body}]'
76
+ ```
77
+
78
+ 2. **Make the changes on the PR's branch.** Check out the PR's head branch, make the minimal fixes the feedback calls for, and push. Committing and pushing to your own branch is `typeclaw-git` territory — follow it for commit hygiene. Do **not** open a _new_ PR to fix your existing one; push to the same branch so the open PR updates in place.
79
+
80
+ ```sh
81
+ gh pr checkout <N> --repo owner/repo
82
+ # …edit files, then commit + push per typeclaw-git…
83
+ ```
84
+
85
+ If a point is a genuine disagreement (the reviewer is mistaken, or the behavior is intentional), don't silently change it — reply in the thread with your reasoning instead.
86
+
87
+ 3. **Reply to the feedback as the author.** After pushing, acknowledge each addressed thread with a normal `channel_reply` (keep `thread` set to stay in the inline thread; omit it for the PR conversation). Say what you changed ("Fixed — switched to the wiki-link form in `abc1234`") or why you didn't ("Left as-is — this path can't be null because …"). Keep it short.
88
+ - **Do not resolve the threads.** On your own PR the open inline threads were authored by your **reviewer**, not by you — and the base principle is _whoever opened the thread closes it_. Resolving is the reviewer's call once they're satisfied; the runtime enforces this (it only lets you resolve threads whose root comment **you** authored). Push the fix, reply, and leave the thread for the reviewer to close.
89
+ - **Do not post a verdict.** "LGTM", "Approved", "Request changes" are reviewer words. As the author you reply in plain prose; you never emit a review verdict on your own PR.
90
+
91
+ 4. **If CI is failing on your PR**, that's also contributor work: read the failing check, fix the cause on the branch, and push. You can't always read another system's CI logs — if you can't, say so and ask for the error rather than guessing.
92
+
93
+ That's the whole contributor loop: read feedback → fix on the branch → push → reply. No subagent, no formal review, no thread resolution.
48
94
 
49
95
  ### When you are being asked to review
50
96