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 +1 -1
- package/src/agent/attention-escalation.ts +11 -1
- package/src/agent/subagents.ts +6 -2
- package/src/agent/tools/channel-reply.ts +48 -3
- package/src/agent/tools/ddg.ts +40 -5
- package/src/agent/tools/keyed-semaphore.ts +114 -0
- package/src/agent/tools/search-retry.ts +82 -0
- package/src/bundled-plugins/explorer/explorer.ts +5 -0
- package/src/bundled-plugins/memory/README.md +2 -2
- package/src/bundled-plugins/memory/append-tool.ts +42 -4
- package/src/bundled-plugins/memory/memory-logger.ts +7 -3
- package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
- package/src/bundled-plugins/scout/scout.ts +5 -0
- package/src/channels/adapters/github/permission-guidance.ts +18 -0
- package/src/cli/channel.ts +7 -11
- package/src/cli/init.ts +2 -2
- package/src/cli/plugin-commands-dispatch.ts +7 -1
- package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
package/package.json
CHANGED
|
@@ -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
|
}
|
package/src/agent/subagents.ts
CHANGED
|
@@ -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
|
|
96
|
-
'
|
|
97
|
-
"It is safe to set by default: the runtime resolves
|
|
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
|
package/src/agent/tools/ddg.ts
CHANGED
|
@@ -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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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 (
|
|
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 (
|
|
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
|
-
|
|
108
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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:
|
package/src/cli/channel.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
'
|
|
1201
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
40
|
-
|
|
|
41
|
-
| **New issue** (`issue:N`)
|
|
42
|
-
| **Issue comment** (`issue:N`)
|
|
43
|
-
| **PR conversation comment** (`pr:N`, no `thread`)
|
|
44
|
-
| **PR review-thread reply** (`pr:N`, `thread` set)
|
|
45
|
-
| **A submitted review** (`pr:N`)
|
|
46
|
-
| **
|
|
47
|
-
| **
|
|
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
|
|