typeclaw 0.48.4 → 0.48.6
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/index.ts +6 -1
- package/src/agent/live-subagents.ts +15 -0
- package/src/agent/plugin-tools.ts +1 -1
- package/src/agent/session-origin.ts +104 -16
- package/src/agent/subagent-completion-reminder.ts +1 -1
- package/src/agent/subagent-drain.ts +11 -1
- package/src/agent/subagents.ts +52 -7
- package/src/agent/tools/post-github-review.ts +101 -1
- package/src/agent/tools/spawn-subagent.ts +88 -7
- package/src/agent/tools/subagent-cancel.ts +1 -0
- package/src/agent/tools/subagent-output.ts +7 -2
- package/src/agent/tools/webfetch/adaptive-html.ts +319 -0
- package/src/agent/tools/webfetch/html-lexical.ts +841 -0
- package/src/agent/tools/webfetch/inline-style-visibility.ts +281 -0
- package/src/agent/tools/webfetch/strategies/readability.ts +306 -5
- package/src/agent/tools/webfetch/tool.ts +45 -2
- package/src/agent/tools/webfetch/types.ts +7 -0
- package/src/agent/turn-runner.ts +7 -3
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +187 -8
- package/src/bundled-plugins/memory/dreaming.ts +3 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +32 -5
- package/src/bundled-plugins/reviewer/skills/code-review.ts +5 -3
- package/src/bundled-plugins/reviewer/skills/doc-review.ts +1 -1
- package/src/bundled-plugins/reviewer/skills/plan-review.ts +1 -1
- package/src/channels/github-review-verdict-coordinator.ts +23 -5
- package/src/channels/router.ts +15 -5
- package/src/cli/inspect.ts +2 -2
- package/src/container/start.ts +16 -0
- package/src/git/resolve-identity.ts +66 -0
- package/src/git/run.ts +2 -0
- package/src/git/system-commit.ts +2 -2
- package/src/inspect/item-list.ts +2 -11
- package/src/inspect/session-list.ts +29 -15
- package/src/plugin/types.ts +0 -10
- package/src/run/channel-session-factory.ts +3 -1
- package/src/run/index.ts +29 -29
- package/src/run/subagent-coalescing.ts +24 -0
- package/src/sandbox/env-exposure.ts +20 -7
- package/src/server/index.ts +4 -1
- package/src/skills/typeclaw-channel-github/SKILL.md +10 -10
- package/src/skills/typeclaw-channel-instagram/SKILL.md +1 -1
- package/src/skills/typeclaw-channel-kakaotalk/SKILL.md +1 -1
- package/src/skills/typeclaw-channel-line/SKILL.md +1 -1
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { Type } from '@mariozechner/pi-ai'
|
|
2
2
|
import { defineTool } from '@mariozechner/pi-coding-agent'
|
|
3
3
|
|
|
4
|
+
import { extractAdaptiveHtml, validateAdaptiveHtmlComplexity } from './adaptive-html'
|
|
4
5
|
import { fetchWithLimits, normalizeUrl, parseMimeType, WebFetchError } from './fetch'
|
|
5
6
|
import { applyGrep, GrepError } from './strategies/grep'
|
|
6
7
|
import { applyJq, JqError } from './strategies/jq'
|
|
@@ -14,6 +15,7 @@ import {
|
|
|
14
15
|
MAX_TIMEOUT_SECONDS,
|
|
15
16
|
OUTPUT_CAPS,
|
|
16
17
|
type WebFetchDetails,
|
|
18
|
+
type HtmlExtractionAttempt,
|
|
17
19
|
} from './types'
|
|
18
20
|
|
|
19
21
|
const STRATEGY_VALUES = ['readability', 'jq', 'selector', 'grep', 'snapshot', 'raw'] as const
|
|
@@ -32,7 +34,12 @@ export const webFetchTool = defineTool({
|
|
|
32
34
|
'fingerprinting (mouse/scroll/timing), interactive CAPTCHAs, or IP-reputation blocks — a 403 from those ' +
|
|
33
35
|
'layers is expected and unrecoverable from this tool. ' +
|
|
34
36
|
'Strategy guide:\n' +
|
|
35
|
-
'- "readability": extract article content as markdown (blogs, docs, news). Default for HTML
|
|
37
|
+
'- "readability": extract article content as markdown (blogs, docs, news). Default for HTML — when auto-detected, ' +
|
|
38
|
+
'a linear DOM-complexity preflight (5 MiB scan, 20,000 tags, 256 nesting levels) runs before Readability; a ' +
|
|
39
|
+
'Readability miss (e.g. a JS app shell with no visible content) is rescued by scanning for a bounded schema.org ' +
|
|
40
|
+
'Article/NewsArticle/BlogPosting JSON-LD block before giving up; if neither yields meaningful text the error says ' +
|
|
41
|
+
'browser retrieval may be needed. Passing `strategy: "readability"` explicitly skips adaptive JSON-LD/classification ' +
|
|
42
|
+
"and returns Readability's result as-is, even when empty, but still shares parser and deterministic visibility safety checks.\n" +
|
|
36
43
|
'- "jq": query JSON APIs (npm registry, GitHub API). Pass `query` (e.g. ".items[].name").\n' +
|
|
37
44
|
'- "selector": extract text from elements matching a CSS selector. Pass `selector` (e.g. ".price").\n' +
|
|
38
45
|
'- "grep": filter lines by regex with optional `before`/`after` context. Pass `pattern`.\n' +
|
|
@@ -125,8 +132,41 @@ export const webFetchTool = defineTool({
|
|
|
125
132
|
}
|
|
126
133
|
|
|
127
134
|
let output: string
|
|
135
|
+
let extractionAttempts: HtmlExtractionAttempt[] | undefined
|
|
128
136
|
try {
|
|
129
|
-
|
|
137
|
+
if (strategy === 'readability' && autoDetected) {
|
|
138
|
+
const extracted = await extractAdaptiveHtml(response.body, response.finalUrl)
|
|
139
|
+
extractionAttempts = extracted.attempts
|
|
140
|
+
if (extracted.kind === 'error') {
|
|
141
|
+
return errorResult(normalizedUrl, extracted.message, {
|
|
142
|
+
startedAt,
|
|
143
|
+
finalUrl: response.finalUrl,
|
|
144
|
+
contentType: response.contentType,
|
|
145
|
+
httpStatus: response.httpStatus,
|
|
146
|
+
bytesIn: response.bytesIn,
|
|
147
|
+
strategy,
|
|
148
|
+
autoDetected,
|
|
149
|
+
extractionAttempts,
|
|
150
|
+
})
|
|
151
|
+
}
|
|
152
|
+
output = extracted.output
|
|
153
|
+
} else {
|
|
154
|
+
if (strategy === 'readability') {
|
|
155
|
+
const complexity = validateAdaptiveHtmlComplexity(response.body)
|
|
156
|
+
if (!complexity.valid) {
|
|
157
|
+
return errorResult(normalizedUrl, complexity.reason, {
|
|
158
|
+
startedAt,
|
|
159
|
+
finalUrl: response.finalUrl,
|
|
160
|
+
contentType: response.contentType,
|
|
161
|
+
httpStatus: response.httpStatus,
|
|
162
|
+
bytesIn: response.bytesIn,
|
|
163
|
+
strategy,
|
|
164
|
+
autoDetected,
|
|
165
|
+
})
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
output = await runStrategy(strategy, response.body, response.finalUrl, params)
|
|
169
|
+
}
|
|
130
170
|
} catch (error) {
|
|
131
171
|
const message = error instanceof Error ? error.message : String(error)
|
|
132
172
|
return errorResult(normalizedUrl, message, {
|
|
@@ -152,6 +192,7 @@ export const webFetchTool = defineTool({
|
|
|
152
192
|
bytesOut: byteLength(capped.text),
|
|
153
193
|
truncated: capped.truncated,
|
|
154
194
|
durationMs: Date.now() - startedAt,
|
|
195
|
+
...(extractionAttempts === undefined ? {} : { extractionAttempts }),
|
|
155
196
|
...(response.antibotWarmup?.triggered
|
|
156
197
|
? {
|
|
157
198
|
antibotWarmup: {
|
|
@@ -286,6 +327,8 @@ function errorResult(
|
|
|
286
327
|
bytesOut: byteLength(message),
|
|
287
328
|
truncated: false,
|
|
288
329
|
durationMs: Date.now() - startedAt,
|
|
330
|
+
...(rest.antibotWarmup === undefined ? {} : { antibotWarmup: rest.antibotWarmup }),
|
|
331
|
+
...(rest.extractionAttempts === undefined ? {} : { extractionAttempts: rest.extractionAttempts }),
|
|
289
332
|
error: true,
|
|
290
333
|
message,
|
|
291
334
|
}
|
|
@@ -7,6 +7,12 @@ export type AntibotWarmupDetails = {
|
|
|
7
7
|
replayStatus?: number
|
|
8
8
|
}
|
|
9
9
|
|
|
10
|
+
export type HtmlExtractionAttempt = {
|
|
11
|
+
route: 'readability' | 'json_ld'
|
|
12
|
+
outcome: 'success' | 'unusable' | 'error'
|
|
13
|
+
reason: string
|
|
14
|
+
}
|
|
15
|
+
|
|
10
16
|
export type WebFetchDetails = {
|
|
11
17
|
url: string
|
|
12
18
|
finalUrl: string
|
|
@@ -19,6 +25,7 @@ export type WebFetchDetails = {
|
|
|
19
25
|
truncated: boolean
|
|
20
26
|
durationMs: number
|
|
21
27
|
antibotWarmup?: AntibotWarmupDetails
|
|
28
|
+
extractionAttempts?: HtmlExtractionAttempt[]
|
|
22
29
|
error?: boolean
|
|
23
30
|
message?: string
|
|
24
31
|
}
|
package/src/agent/turn-runner.ts
CHANGED
|
@@ -37,9 +37,13 @@ type AttemptActivity = {
|
|
|
37
37
|
startedToolExecution: boolean
|
|
38
38
|
}
|
|
39
39
|
|
|
40
|
-
// SDK-level attempts already contain pi-ai's internal fetch recovery.
|
|
41
|
-
//
|
|
42
|
-
//
|
|
40
|
+
// SDK-level attempts already contain pi-ai's internal fetch recovery. Three is
|
|
41
|
+
// the safe minimum for a fallback chain: primary attempt + its one ordinary
|
|
42
|
+
// transient replay + one cross-ref attempt. Lowering it would weaken either the
|
|
43
|
+
// retained transient retry or fallback; raising it would recreate the repeated
|
|
44
|
+
// TTFB bursts reviewer coalescing is intended to prevent from multiplying.
|
|
45
|
+
// Patient overload retries do not apply to observer TTFB errors, so this envelope
|
|
46
|
+
// already bounds deep-review no-progress without a reviewer-specific retry fork.
|
|
43
47
|
const MAX_NO_PROGRESS_ATTEMPTS = 3
|
|
44
48
|
const MAX_CUMULATIVE_NO_PROGRESS_MS = 60_000
|
|
45
49
|
|
|
@@ -79,7 +79,7 @@ const COMPOSITION_REASON =
|
|
|
79
79
|
'newlines, redirections, command/process substitution, subshells, heredocs, or unquoted ' +
|
|
80
80
|
'`$` expansion (any sibling process or expansion would inherit the token and could ' +
|
|
81
81
|
'exfiltrate it). One exception is allowed: a trailing reader pipeline `gh … | <reader>` ' +
|
|
82
|
-
'where every downstream stage is a stdin-only reader (`jq`, `cat`, `wc`, `sort`, `uniq`) ' +
|
|
82
|
+
'where every downstream stage is a stdin-only reader (`jq`, `grep`, `cat`, `wc`, `sort`, `uniq`) ' +
|
|
83
83
|
'with no file operand — e.g. `gh api repos/o/r | jq .`. jq/JSON metacharacters are also ' +
|
|
84
84
|
"fine INSIDE single quotes, e.g. `gh api repos/o/r --jq '.[] | {id}'`. File-backed " +
|
|
85
85
|
'`--input`, `--body-file`, templates, aliases, extensions, and auth/config commands remain unavailable.'
|
|
@@ -262,7 +262,7 @@ function isAuthStatusTokenDisplayFlag(arg: string): boolean {
|
|
|
262
262
|
|
|
263
263
|
export function canInjectPatIntoPassThroughGh(command: string): boolean {
|
|
264
264
|
if (containsReviewGraphqlMutation(command)) return false
|
|
265
|
-
if (command
|
|
265
|
+
if (hasUnsafeGhStageBackslash(command)) return false
|
|
266
266
|
if (!isSingleBareGhCommand(command)) return false
|
|
267
267
|
const tokens = tokenize(command)
|
|
268
268
|
const starts = findGhInvocations(tokens)
|
|
@@ -410,7 +410,7 @@ function isCredentialSafeGhCommand(command: string): boolean {
|
|
|
410
410
|
const stages = splitTopLevelPipeStages(command)
|
|
411
411
|
if (stages === null || stages.length === 0) return false
|
|
412
412
|
const ghStage = (stages[0] as string).trim()
|
|
413
|
-
if (!isSingleBareGhCommand(ghStage) || ghStage
|
|
413
|
+
if (!isSingleBareGhCommand(ghStage) || hasUnsafeGhStageBackslash(ghStage)) return false
|
|
414
414
|
const tokens = tokenize(ghStage)
|
|
415
415
|
return tokens[0] === 'gh' && isCredentialSafeGhArgs(tokens.slice(1))
|
|
416
416
|
}
|
|
@@ -500,9 +500,11 @@ function isSafeGhJqFilter(filter: string): boolean {
|
|
|
500
500
|
// has gh's output) — they cannot open their own network/file/process sink, so a
|
|
501
501
|
// `gh <repo> | <reader>` pipeline cannot exfiltrate the minted token to a third
|
|
502
502
|
// party. EXCLUDED on purpose: awk (system()/getline|cmd/inet), sed (GNU `e`
|
|
503
|
-
// shell-exec), tee/xargs (write/spawn), less (`!cmd`), and
|
|
503
|
+
// shell-exec), tee/xargs (write/spawn), less (`!cmd`), and head/tail (their
|
|
504
504
|
// file-operand forms are too easy to abuse and not worth the parser risk yet).
|
|
505
|
-
|
|
505
|
+
// grep is admitted through a dedicated grammar that requires a pattern and
|
|
506
|
+
// proves there is no file operand or pattern-file/recursive option.
|
|
507
|
+
const READER_ALLOWLIST = new Set(['jq', 'grep', 'cat', 'wc', 'sort', 'uniq'])
|
|
506
508
|
|
|
507
509
|
// STRICT per-command flag allowlists. We allow ONLY flags known to be pure
|
|
508
510
|
// stdin-shaping (no file/program operand). This is allow-known-good, not
|
|
@@ -561,6 +563,22 @@ const JQ_SAFE_VALUE_LONG: Record<string, number> = {
|
|
|
561
563
|
// (module path) are the fatal ones — and any unknown char also rejects.
|
|
562
564
|
const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', 'j', 'C', 'M', 'b'])
|
|
563
565
|
|
|
566
|
+
const GREP_SAFE_BOOLEAN_LONG = new Set([
|
|
567
|
+
'--basic-regexp',
|
|
568
|
+
'--extended-regexp',
|
|
569
|
+
'--fixed-strings',
|
|
570
|
+
'--ignore-case',
|
|
571
|
+
'--invert-match',
|
|
572
|
+
'--line-number',
|
|
573
|
+
'--count',
|
|
574
|
+
'--only-matching',
|
|
575
|
+
'--quiet',
|
|
576
|
+
'--silent',
|
|
577
|
+
'--word-regexp',
|
|
578
|
+
'--line-regexp',
|
|
579
|
+
])
|
|
580
|
+
const GREP_SAFE_BOOLEAN_SHORT = new Set(['E', 'F', 'G', 'i', 'v', 'n', 'c', 'o', 'q', 'w', 'x'])
|
|
581
|
+
|
|
564
582
|
// A reader stage is safe only if it is an allowlisted command using ONLY its
|
|
565
583
|
// known stdin-shaping flags, with no file operand. Backslashes are rejected
|
|
566
584
|
// outright: our tokenizer does not model shell backslash escaping, so a
|
|
@@ -568,12 +586,13 @@ const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', '
|
|
|
568
586
|
// as the forbidden flag — an allowlist-bypass. Rejecting `\` closes that gap.
|
|
569
587
|
function isStdinOnlyReaderStage(stage: string): boolean {
|
|
570
588
|
if (containsShellActiveMetachar(stage)) return false
|
|
571
|
-
if (stage.includes('\\')) return false
|
|
572
589
|
const tokens = splitStageTokens(stage)
|
|
573
590
|
const cmd = tokens[0]
|
|
574
591
|
if (cmd === undefined || !READER_ALLOWLIST.has(cmd)) return false
|
|
575
592
|
|
|
576
|
-
if (cmd === 'jq') return isStdinOnlyJqStage(tokens)
|
|
593
|
+
if (cmd === 'jq') return !hasUnsafeJqStageBackslash(stage) && isStdinOnlyJqStage(tokens)
|
|
594
|
+
if (stage.includes('\\')) return false
|
|
595
|
+
if (cmd === 'grep') return isStdinOnlyGrepStage(tokens)
|
|
577
596
|
|
|
578
597
|
const allowedFlags = READER_BOOLEAN_FLAGS[cmd]
|
|
579
598
|
if (allowedFlags === undefined) return false
|
|
@@ -585,6 +604,65 @@ function isStdinOnlyReaderStage(stage: string): boolean {
|
|
|
585
604
|
return true
|
|
586
605
|
}
|
|
587
606
|
|
|
607
|
+
// grep reads stdin only when its argv contains one positional pattern OR one or
|
|
608
|
+
// more -e/--regexp patterns, followed by no positional file operands. Keep the
|
|
609
|
+
// option surface intentionally small: unknown options fail closed, especially
|
|
610
|
+
// -f/--file, recursive traversal, and include/exclude selectors.
|
|
611
|
+
function isStdinOnlyGrepStage(tokens: readonly string[]): boolean {
|
|
612
|
+
let patternCount = 0
|
|
613
|
+
let usesRegexpFlag = false
|
|
614
|
+
let sawPositionalPattern = false
|
|
615
|
+
for (let i = 1; i < tokens.length; i++) {
|
|
616
|
+
const tok = tokens[i] as string
|
|
617
|
+
if (tok === '--') return false
|
|
618
|
+
if (sawPositionalPattern && tok.startsWith('-')) return false
|
|
619
|
+
if (tok === '-e' || tok === '--regexp') {
|
|
620
|
+
if (sawPositionalPattern) return false
|
|
621
|
+
const pattern = tokens[i + 1]
|
|
622
|
+
if (pattern === undefined) return false
|
|
623
|
+
patternCount += 1
|
|
624
|
+
usesRegexpFlag = true
|
|
625
|
+
i += 1
|
|
626
|
+
continue
|
|
627
|
+
}
|
|
628
|
+
if (tok.startsWith('--regexp=')) {
|
|
629
|
+
if (sawPositionalPattern) return false
|
|
630
|
+
patternCount += 1
|
|
631
|
+
usesRegexpFlag = true
|
|
632
|
+
continue
|
|
633
|
+
}
|
|
634
|
+
if (tok.startsWith('--')) {
|
|
635
|
+
if (!GREP_SAFE_BOOLEAN_LONG.has(tok)) return false
|
|
636
|
+
continue
|
|
637
|
+
}
|
|
638
|
+
if (tok.startsWith('-') && tok.length > 1) {
|
|
639
|
+
const shortOptions = tok.slice(1)
|
|
640
|
+
for (let shortIndex = 0; shortIndex < shortOptions.length; shortIndex++) {
|
|
641
|
+
const ch = shortOptions[shortIndex] as string
|
|
642
|
+
if (ch === 'e') {
|
|
643
|
+
if (sawPositionalPattern) return false
|
|
644
|
+
patternCount += 1
|
|
645
|
+
usesRegexpFlag = true
|
|
646
|
+
// grep treats `e` as a value-taking terminal option: the rest of the
|
|
647
|
+
// cluster is its pattern (`-neerror`), or the next token is (`-ne x`).
|
|
648
|
+
// No later cluster character can therefore become another option.
|
|
649
|
+
if (shortIndex + 1 < shortOptions.length) break
|
|
650
|
+
const pattern = tokens[i + 1]
|
|
651
|
+
if (pattern === undefined) return false
|
|
652
|
+
i += 1
|
|
653
|
+
break
|
|
654
|
+
}
|
|
655
|
+
if (!GREP_SAFE_BOOLEAN_SHORT.has(ch)) return false
|
|
656
|
+
}
|
|
657
|
+
continue
|
|
658
|
+
}
|
|
659
|
+
if (usesRegexpFlag || patternCount > 0) return false
|
|
660
|
+
patternCount = 1
|
|
661
|
+
sawPositionalPattern = true
|
|
662
|
+
}
|
|
663
|
+
return patternCount > 0
|
|
664
|
+
}
|
|
665
|
+
|
|
588
666
|
// jq must run pure-stdin: only known stdin-shaping flags, and EXACTLY one
|
|
589
667
|
// positional (the filter). A second positional is an input FILE jq would open
|
|
590
668
|
// (`jq . /proc/self/environ` reads that file), so it is rejected. The filter is
|
|
@@ -641,10 +719,18 @@ function analyzeReaderPipeline(command: string, stripRepoFlag: boolean): string
|
|
|
641
719
|
}
|
|
642
720
|
|
|
643
721
|
const rewrittenGh = stripRepoFlag ? stripRepoFlagFromCommand(ghStage) : ghStage
|
|
644
|
-
const rewrittenReaders = stages.slice(1).map(
|
|
722
|
+
const rewrittenReaders = stages.slice(1).map(rewriteReaderStage)
|
|
645
723
|
return [rewrittenGh, ...rewrittenReaders].join(' | ')
|
|
646
724
|
}
|
|
647
725
|
|
|
726
|
+
function rewriteReaderStage(stage: string): string {
|
|
727
|
+
const trimmed = stage.trim()
|
|
728
|
+
if (splitStageTokens(trimmed)[0] === 'grep') {
|
|
729
|
+
return `/usr/bin/env -u GH_TOKEN -u GITHUB_TOKEN -u GREP_OPTIONS /usr/bin/grep${trimmed.slice('grep'.length)}`
|
|
730
|
+
}
|
|
731
|
+
return `/usr/bin/env -u GH_TOKEN -u GITHUB_TOKEN ${trimmed}`
|
|
732
|
+
}
|
|
733
|
+
|
|
648
734
|
// Quote-aware split on top-level `|`. Returns null if any OTHER shell-active
|
|
649
735
|
// metachar appears outside single quotes (`;` `&` `<` `>` backtick `$` `(` `)`
|
|
650
736
|
// `{` `}` newline) or if a `||`/`|&` is seen — those are not simple pipelines.
|
|
@@ -742,6 +828,99 @@ function splitStageTokens(stage: string): string[] {
|
|
|
742
828
|
return tokens
|
|
743
829
|
}
|
|
744
830
|
|
|
831
|
+
// Backslashes are shell-active outside single quotes, and the argv-ish tokenizers
|
|
832
|
+
// below deliberately do not interpret shell escapes. The one safe use we support
|
|
833
|
+
// is jq syntax such as `split("\\n")` when the complete filter operand is
|
|
834
|
+
// single-quoted: the shell passes that backslash literally to jq, so it cannot
|
|
835
|
+
// disguise a forbidden gh/jq flag or file operand.
|
|
836
|
+
function hasUnsafeGhStageBackslash(stage: string): boolean {
|
|
837
|
+
if (!stage.includes('\\')) return false
|
|
838
|
+
const rawTokens = splitRawStageTokens(stage)
|
|
839
|
+
if (rawTokens === null) return true
|
|
840
|
+
|
|
841
|
+
for (let i = 0; i < rawTokens.length; i++) {
|
|
842
|
+
const raw = rawTokens[i] as string
|
|
843
|
+
if (!raw.includes('\\')) continue
|
|
844
|
+
const previous = rawTokens[i - 1]
|
|
845
|
+
if ((previous === '--jq' || previous === '-q') && isFullySingleQuoted(raw)) continue
|
|
846
|
+
const attachedFilter = raw.startsWith('--jq=')
|
|
847
|
+
? raw.slice('--jq='.length)
|
|
848
|
+
: raw.startsWith('-q=')
|
|
849
|
+
? raw.slice(3)
|
|
850
|
+
: null
|
|
851
|
+
if (attachedFilter !== null && isFullySingleQuoted(attachedFilter)) continue
|
|
852
|
+
return true
|
|
853
|
+
}
|
|
854
|
+
return false
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
function hasUnsafeJqStageBackslash(stage: string): boolean {
|
|
858
|
+
if (!stage.includes('\\')) return false
|
|
859
|
+
const rawTokens = splitRawStageTokens(stage)
|
|
860
|
+
if (rawTokens === null || rawTokens[0] !== 'jq') return true
|
|
861
|
+
|
|
862
|
+
let filterIndex: number | null = null
|
|
863
|
+
for (let i = 1; i < rawTokens.length; i++) {
|
|
864
|
+
const token = stripPairedQuotes(rawTokens[i] as string)
|
|
865
|
+
if (token === '--') return true
|
|
866
|
+
if (token.startsWith('--')) {
|
|
867
|
+
const consume = JQ_SAFE_VALUE_LONG[token]
|
|
868
|
+
if (consume !== undefined) i += consume
|
|
869
|
+
continue
|
|
870
|
+
}
|
|
871
|
+
if (token.startsWith('-') && token.length > 1) continue
|
|
872
|
+
filterIndex = i
|
|
873
|
+
break
|
|
874
|
+
}
|
|
875
|
+
|
|
876
|
+
for (let i = 1; i < rawTokens.length; i++) {
|
|
877
|
+
const raw = rawTokens[i] as string
|
|
878
|
+
if (!raw.includes('\\')) continue
|
|
879
|
+
if (i === filterIndex && isFullySingleQuoted(raw)) continue
|
|
880
|
+
return true
|
|
881
|
+
}
|
|
882
|
+
return false
|
|
883
|
+
}
|
|
884
|
+
|
|
885
|
+
function splitRawStageTokens(stage: string): string[] | null {
|
|
886
|
+
const tokens: string[] = []
|
|
887
|
+
let current = ''
|
|
888
|
+
let quote: '"' | "'" | null = null
|
|
889
|
+
for (const ch of stage) {
|
|
890
|
+
if (quote !== null) {
|
|
891
|
+
current += ch
|
|
892
|
+
if (ch === quote) quote = null
|
|
893
|
+
continue
|
|
894
|
+
}
|
|
895
|
+
if (ch === '"' || ch === "'") {
|
|
896
|
+
quote = ch
|
|
897
|
+
current += ch
|
|
898
|
+
continue
|
|
899
|
+
}
|
|
900
|
+
if (ch === ' ' || ch === '\t') {
|
|
901
|
+
if (current !== '') {
|
|
902
|
+
tokens.push(current)
|
|
903
|
+
current = ''
|
|
904
|
+
}
|
|
905
|
+
continue
|
|
906
|
+
}
|
|
907
|
+
current += ch
|
|
908
|
+
}
|
|
909
|
+
if (quote !== null) return null
|
|
910
|
+
if (current !== '') tokens.push(current)
|
|
911
|
+
return tokens
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
function isFullySingleQuoted(raw: string): boolean {
|
|
915
|
+
return raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'") && !raw.slice(1, -1).includes("'")
|
|
916
|
+
}
|
|
917
|
+
|
|
918
|
+
function stripPairedQuotes(raw: string): string {
|
|
919
|
+
if (raw.length < 2) return raw
|
|
920
|
+
const first = raw[0]
|
|
921
|
+
return first === raw[raw.length - 1] && (first === '"' || first === "'") ? raw.slice(1, -1) : raw
|
|
922
|
+
}
|
|
923
|
+
|
|
745
924
|
// Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single
|
|
746
925
|
// bare command, preserving everything else byte-for-byte. Quote-aware so a `-R`
|
|
747
926
|
// inside a quoted `-f query='...'` value is never touched; a repo slug is
|
|
@@ -745,8 +745,9 @@ async function ensureMemoryFiles(agentDir: string): Promise<void> {
|
|
|
745
745
|
|
|
746
746
|
// Force-add gitignored memory artifacts so the agent folder's git history
|
|
747
747
|
// captures consolidation as a single recoverable snapshot. Skips silently when
|
|
748
|
-
// the folder is not a git repo or bun is unavailable. Uses
|
|
749
|
-
//
|
|
748
|
+
// the folder is not a git repo or bun is unavailable. Uses Git's ambient
|
|
749
|
+
// identity: host config in host-stage calls, or the agent repo identity
|
|
750
|
+
// injected into the container process at start.
|
|
750
751
|
//
|
|
751
752
|
// After committing, the tracked memory artifacts get the `skip-worktree` index
|
|
752
753
|
// flag set so manual `git status` / `git diff` ignore future runtime edits.
|
|
@@ -81,7 +81,7 @@ You are STRICTLY PROHIBITED from:
|
|
|
81
81
|
- Pushing, merging, rebasing, or otherwise mutating remote state
|
|
82
82
|
- Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, git push, git rebase, git reset, npm install, pip install, or any write operation
|
|
83
83
|
|
|
84
|
-
The boundary that matters is **no side effects on the reviewed artifact, remote state, or the persistent workspace** — not "no byte may touch local disk". A loaded domain skill may carve out one narrow, explicit exception:
|
|
84
|
+
The boundary that matters is **no side effects on the reviewed artifact, remote state, or the persistent workspace** — not "no byte may touch local disk". A loaded domain skill may carve out one narrow, explicit exception: asking the existing \`github_prepare_review_checkout\` tool to create a throwaway scratch directory under \`/tmp\` purely to acquire a read target. Use its returned receipt path exactly; never guess or reconstruct a \`/tmp\` path. That scratch cache is never the reviewed artifact; inside it you still only read, and everything in the prohibition list above still applies everywhere else. Absent such an instruction from your loaded skill, treat the list as absolute.
|
|
85
85
|
|
|
86
86
|
Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to do with your findings. Delegating part of that analysis is fine; performing side effects through a delegate is NOT — anything you cannot do directly, a subagent you spawn cannot do for you.
|
|
87
87
|
|
|
@@ -94,7 +94,7 @@ This is not a last resort — it is your DEFAULT for any non-trivial target, and
|
|
|
94
94
|
- 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.
|
|
95
95
|
- Each delegated task must be self-contained: the worker does not see this conversation or the target. Put everything it needs in the prompt.
|
|
96
96
|
- The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
|
|
97
|
-
- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned.
|
|
97
|
+
- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Batch independent \`spawn_subagent\` calls in one turn so they run concurrently. For background tasks, end the turn and wait for each completion \`<system-reminder>\`; do not poll \`subagent_output\` before that reminder. Fold all results into one review pass.
|
|
98
98
|
|
|
99
99
|
## Tools
|
|
100
100
|
|
|
@@ -104,12 +104,12 @@ The runtime exposes these tools to you by these EXACT names — call them by nam
|
|
|
104
104
|
- \`grep\` — search file contents by text or regex
|
|
105
105
|
- \`find\` — locate files by name pattern
|
|
106
106
|
- \`ls\` — list a directory's immediate contents
|
|
107
|
-
- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`)
|
|
107
|
+
- \`bash\` — read-only commands ONLY. Use one simple invocation at a time: no shell loops, pipelines, redirects, \`&&\`, or \`;\`. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) is allowed. For platform-specific reads, use the canonical single invocation from the loaded skill. Never create or reconstruct a review checkout with bash; only the existing checkout tool may acquire one.
|
|
108
108
|
- \`web_search\` — search the public web (e.g. for OWASP guidance, RFCs, library changelogs, framework docs, prior art)
|
|
109
109
|
- \`web_fetch\` — fetch a single URL (e.g. to read a linked spec, vendor doc, or article cited in the target)
|
|
110
110
|
- \`load_skill\` — load a curated review skill by name. See the section below.
|
|
111
111
|
|
|
112
|
-
|
|
112
|
+
Batch independent reads and searches in parallel. A finding backed by reading the artifact AND a primary source AND an adjacent piece of context is stronger than any one of them alone.
|
|
113
113
|
|
|
114
114
|
## Loading a review skill
|
|
115
115
|
|
|
@@ -180,11 +180,22 @@ These three tokens are the universal verdict vocabulary — they apply whether t
|
|
|
180
180
|
|
|
181
181
|
You have one shot. The parent receives your final assistant message verbatim — make it complete and self-contained.`
|
|
182
182
|
|
|
183
|
+
export const reviewerReviewIdentitySchema = z.object({
|
|
184
|
+
repo: z.string().regex(/^[^/\s]+\/[^/\s]+$/),
|
|
185
|
+
pullRequest: z.number().int().positive(),
|
|
186
|
+
headSha: z.string().regex(/^[0-9a-f]{40}$/i),
|
|
187
|
+
baseSha: z.string().regex(/^[0-9a-f]{40}$/i),
|
|
188
|
+
reviewKind: z.enum(['review', 're-review']),
|
|
189
|
+
})
|
|
190
|
+
|
|
191
|
+
export type ReviewerReviewIdentity = z.infer<typeof reviewerReviewIdentitySchema>
|
|
192
|
+
|
|
183
193
|
export const reviewerPayloadSchema = z
|
|
184
194
|
.object({
|
|
185
195
|
requestId: z.string().optional(),
|
|
186
196
|
prompt: z.string().optional(),
|
|
187
197
|
description: z.string().optional(),
|
|
198
|
+
reviewIdentity: reviewerReviewIdentitySchema.optional(),
|
|
188
199
|
})
|
|
189
200
|
.passthrough()
|
|
190
201
|
|
|
@@ -225,7 +236,13 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
|
|
|
225
236
|
canSpawnSubagents: true,
|
|
226
237
|
canBackgroundSpawnSubagents: true,
|
|
227
238
|
timeoutMs: REVIEWER_SPAWN_TIMEOUT_MS,
|
|
228
|
-
|
|
239
|
+
// Only PR jobs opt into stable coalescing. General code/plan/document
|
|
240
|
+
// reviews retain request-scoped concurrency; deriving identity from prompt
|
|
241
|
+
// prose would risk collapsing unrelated work or reviews of different heads.
|
|
242
|
+
inFlightKey: (payload) =>
|
|
243
|
+
payload.reviewIdentity === undefined
|
|
244
|
+
? (payload.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`)
|
|
245
|
+
: reviewerReviewIdentityKey(payload.reviewIdentity),
|
|
229
246
|
toolResultBudget: {
|
|
230
247
|
// Higher than explorer (256KB) because a reviewer typically reads larger
|
|
231
248
|
// diffs and multiple files plus web sources; lower than operator (1MB)
|
|
@@ -235,3 +252,13 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
|
|
|
235
252
|
},
|
|
236
253
|
}
|
|
237
254
|
}
|
|
255
|
+
|
|
256
|
+
export function reviewerReviewIdentityKey(identity: ReviewerReviewIdentity): string {
|
|
257
|
+
return [
|
|
258
|
+
identity.repo.toLocaleLowerCase(),
|
|
259
|
+
identity.pullRequest,
|
|
260
|
+
identity.headSha.toLocaleLowerCase(),
|
|
261
|
+
identity.baseSha.toLocaleLowerCase(),
|
|
262
|
+
identity.reviewKind.toLocaleLowerCase(),
|
|
263
|
+
].join('#')
|
|
264
|
+
}
|
|
@@ -35,11 +35,11 @@ gh api "/repos/<owner>/<repo>/contents/<path>?ref=<headSha>" -H "Accept: applica
|
|
|
35
35
|
|
|
36
36
|
That returns the file's raw bytes (no base64, no second stage). For the line numbers your \`location="path:line"\` anchors need, read them off the unified diff you already fetched (\`gh pr diff\` prints the new-side line numbers in its hunk headers, \`@@ -a,b +c,d @@\`), or escalate to Mode 2 where a real \`read\`/\`grep\` gives native line numbers. Fetch each file once and keep its output — do not re-fetch the same file to re-derive a line you already saw.
|
|
37
37
|
|
|
38
|
-
**Mode 2 — scratch checkout (escalate when navigation gets broad).** When navigation gets broad, call \`github_prepare_review_checkout({ repoSlug: "<owner>/<repo>", headSha: "<40-char headSha>" })
|
|
38
|
+
**Mode 2 — scratch checkout (escalate when navigation gets broad).** When navigation gets broad, call \`github_prepare_review_checkout({ repoSlug: "<owner>/<repo>", headSha: "<40-char headSha>" })\` once for initial acquisition. The runtime verifies that exact SHA in the one allowlisted repository and performs the authenticated fetch without exposing its token to model bash.
|
|
39
39
|
|
|
40
|
-
Then use the receipt path with \`read\`, \`grep\`, \`find\`, and read-only \`git\` (\`git -C <receipt-path> log|diff|show|blame|grep|ls-files|cat-file\`) for correct line numbers and zero per-file round-trips. Do not use \`git clone\`, \`git fetch\`, \`git checkout\`, or \`gh pr checkout\` for acquisition.
|
|
40
|
+
Then use the returned receipt path exactly with \`read\`, \`grep\`, \`find\`, and read-only \`git\` (\`git -C <receipt-path> log|diff|show|blame|grep|ls-files|cat-file\`) for correct line numbers and zero per-file round-trips. Trust the receipt: never guess, derive, or reconstruct a \`/tmp\` path. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures, change coordinates, or recover by guessing a path. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review. Do not use \`git clone\`, \`git fetch\`, \`git checkout\`, or \`gh pr checkout\` for acquisition.
|
|
41
41
|
|
|
42
|
-
This \`/tmp\` scratch
|
|
42
|
+
This runtime-owned \`/tmp\` scratch acquisition is the **only kind of write** the read-only contract permits — and only because it is a private acquisition cache, never the reviewed artifact. Inside a returned checkout you may only **read**. You still may NOT: edit any file, install dependencies, run builds or tests, commit/stage/push/rebase/reset, or write anywhere outside the returned \`/tmp\` scratch dir. Do not \`rm\` it when done — leave cleanup to the session lifecycle (\`rm\` stays forbidden). When in doubt about how many files you'll touch, start with Mode 1 and escalate to Mode 2 only once the file count or grep breadth justifies the clone.
|
|
43
43
|
|
|
44
44
|
## Bound your external verification — never loop
|
|
45
45
|
|
|
@@ -128,6 +128,8 @@ Calibrate to consequence, not to spec-completeness. Severity is \`(realistic pro
|
|
|
128
128
|
|
|
129
129
|
When the payload tells you this is a **re-review** — you (or this agent) previously requested changes on this PR and the author has pushed fixes — your verdict's whole purpose is to **re-decide the blocking state**, so:
|
|
130
130
|
|
|
131
|
+
Compare the prior reviewed head with the current head and focus exploration on the intervening changes. Reuse prior findings and already-gathered context instead of repeating the first review, while validating cumulative correctness at the current head: prior blockers are resolved, their fixes introduce no regression, and the full result still serves the stated intent.
|
|
132
|
+
|
|
131
133
|
This includes payloads where the parent says the author **addressed your prior blocking feedback** — "fixed both issues", "addressed your review", "pushed a fix" — even when the inbound was phrased conversationally rather than as an explicit "review again". An author responding to the blocker you raised IS the re-review trigger; the absence of the words "review again" does not downgrade it to a \`comment\`. Re-decide:
|
|
132
134
|
|
|
133
135
|
- Return **approve** if the blockers that drove the prior \`request-changes\` are resolved (leftover nits do not block — \`approve\` with inline nits is correct).
|
|
@@ -13,7 +13,7 @@ You have been asked to review a document — anything written to inform or instr
|
|
|
13
13
|
|
|
14
14
|
- **A file path** — \`read\` it. \`ls\` the surrounding directory to see how this page fits the larger set; a document is reviewed in the context of the set it belongs to.
|
|
15
15
|
- **A URL** — \`web_fetch\` it. If it is a private site the fetch cannot reach, say so in \`<summary>\` and review what the payload provided.
|
|
16
|
-
- **A PR or diff that touches docs** — \`gh pr diff <n>\` for the
|
|
16
|
+
- **A PR or diff that touches docs** — use \`gh pr diff <n>\` for a small change. When broad local context is needed, call \`github_prepare_review_checkout\` once for initial acquisition with the repo slug and 40-character head SHA, then use the returned receipt path exactly for batched \`read\`/\`grep\`/\`find\` calls. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures or change coordinates. Never guess or reconstruct a path or acquire a checkout with bash. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review.
|
|
17
17
|
- **A doc set / directory** — \`ls\` and \`grep\` for the navigation or index file; a finding about findability needs the table of contents, not just one page.
|
|
18
18
|
- **Verify external claims.** If the document cites a law, a standard, a price, an SLA, a statistic, or a linked source, check it with \`web_search\`/\`web_fetch\` before letting it stand.
|
|
19
19
|
|
|
@@ -13,7 +13,7 @@ You have been asked to review a plan — an RFC, a design doc, a PRFAQ, a roadma
|
|
|
13
13
|
|
|
14
14
|
- **A file path** — \`read\` it. \`ls\` the directory for a template or sibling RFCs that establish the expected shape; deviation from an established plan template is itself worth noting.
|
|
15
15
|
- **A URL or doc** — \`web_fetch\` it. If it is a private doc the fetch cannot reach, say so in \`<summary>\` and review what the payload provided.
|
|
16
|
-
- **A PR that adds a design doc** — \`gh pr diff <n
|
|
16
|
+
- **A PR that adds a design doc** — use \`gh pr diff <n>\` for a small change. When broad local context is needed, call \`github_prepare_review_checkout\` once for initial acquisition with the repo slug and 40-character head SHA, then use the returned receipt path exactly for batched \`read\`/\`grep\`/\`find\` calls. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures or change coordinates. Never guess or reconstruct a path or acquire a checkout with bash. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review. Read linked context when referenced; a plan is judged partly on whether it answers the question that prompted it.
|
|
17
17
|
- **An inline plan in the payload** — read it carefully and quote from it when forming evidence.
|
|
18
18
|
|
|
19
19
|
## What to look for
|
|
@@ -23,7 +23,13 @@ export type EffectiveApprovalResolver = (target: {
|
|
|
23
23
|
// push-during-review still blocks a same-verdict duplicate for the lag window.
|
|
24
24
|
export type HeadShaResolver = (target: { workspace: string; prNumber: number }) => Promise<string | null>
|
|
25
25
|
|
|
26
|
-
export type ApproveBlock = {
|
|
26
|
+
export type ApproveBlock = {
|
|
27
|
+
block: true
|
|
28
|
+
kind: 'concurrent' | 'duplicate'
|
|
29
|
+
reason: string
|
|
30
|
+
duplicateSource?: 'standing' | 'recent'
|
|
31
|
+
leaseRetained?: boolean
|
|
32
|
+
}
|
|
27
33
|
|
|
28
34
|
export type ReviewVerdictGuard = {
|
|
29
35
|
guard: (args: {
|
|
@@ -31,6 +37,7 @@ export type ReviewVerdictGuard = {
|
|
|
31
37
|
workspace: string
|
|
32
38
|
prNumber: number
|
|
33
39
|
verdict: ReviewVerdict
|
|
40
|
+
retainDuplicateLease?: boolean
|
|
34
41
|
}) => Promise<ApproveBlock | null>
|
|
35
42
|
release: (args: { callId: string; succeeded: boolean }) => Promise<void>
|
|
36
43
|
// Arms the read-after-write lag shield for a verdict that landed WITHOUT a prior
|
|
@@ -203,7 +210,7 @@ export function createApproveIdempotencyGuard(deps: {
|
|
|
203
210
|
// reclaimable so a crash cannot permanently strand the PR.
|
|
204
211
|
const held = inFlightByPr.get(key)
|
|
205
212
|
if (held !== undefined && now() - held.createdAt < LEASE_TTL_MS) {
|
|
206
|
-
return { block: true, reason: CONCURRENT_REASON }
|
|
213
|
+
return { block: true, kind: 'concurrent', reason: CONCURRENT_REASON }
|
|
207
214
|
}
|
|
208
215
|
const reservation: Reservation = {
|
|
209
216
|
key,
|
|
@@ -232,8 +239,14 @@ export function createApproveIdempotencyGuard(deps: {
|
|
|
232
239
|
// now: a blocked command never reaches tool.after, so release() won't run
|
|
233
240
|
// for this callId. Leaving the lease set would resurrect the strand bug —
|
|
234
241
|
// the GitHub read is authoritative for the standing case.
|
|
235
|
-
releaseReservation(args.callId, reservation)
|
|
236
|
-
return {
|
|
242
|
+
if (args.retainDuplicateLease !== true) releaseReservation(args.callId, reservation)
|
|
243
|
+
return {
|
|
244
|
+
block: true,
|
|
245
|
+
kind: 'duplicate',
|
|
246
|
+
reason: duplicateReason(args.verdict),
|
|
247
|
+
duplicateSource: 'standing',
|
|
248
|
+
...(args.retainDuplicateLease === true ? { leaseRetained: true } : {}),
|
|
249
|
+
}
|
|
237
250
|
}
|
|
238
251
|
|
|
239
252
|
// Layer 3 — duplicate-review cooldown. A recently-landed SAME verdict on the
|
|
@@ -254,7 +267,12 @@ export function createApproveIdempotencyGuard(deps: {
|
|
|
254
267
|
recentlyLandedSame(key, args.verdict, headSha, now)
|
|
255
268
|
) {
|
|
256
269
|
releaseReservation(args.callId, reservation)
|
|
257
|
-
return {
|
|
270
|
+
return {
|
|
271
|
+
block: true,
|
|
272
|
+
kind: 'duplicate',
|
|
273
|
+
reason: duplicateReason(args.verdict),
|
|
274
|
+
duplicateSource: 'recent',
|
|
275
|
+
}
|
|
258
276
|
}
|
|
259
277
|
|
|
260
278
|
return null
|