forked from sanbuphy/learn-coding-agent
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathclaudeCodeHints.ts
More file actions
193 lines (167 loc) · 6.32 KB
/
claudeCodeHints.ts
File metadata and controls
193 lines (167 loc) · 6.32 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
/**
* Claude Code hints protocol.
*
* CLIs and SDKs running under Claude Code can emit a self-closing
* `<claude-code-hint />` tag to stderr (merged into stdout by the shell
* tools). The harness scans tool output for these tags, strips them before
* the output reaches the model, and surfaces an install prompt to the
* user — no inference, no proactive execution.
*
* This file provides both the parser and a small module-level store for
* the pending hint. The store is a single slot (not a queue) — we surface
* at most one prompt per session, so there's no reason to accumulate.
* React subscribes via useSyncExternalStore.
*
* See docs/claude-code-hints.md for the vendor-facing spec.
*/
import { logForDebugging } from './debug.js'
import { createSignal } from './signal.js'
export type ClaudeCodeHintType = 'plugin'
export type ClaudeCodeHint = {
/** Spec version declared by the emitter. Unknown versions are dropped. */
v: number
/** Hint discriminator. v1 defines only `plugin`. */
type: ClaudeCodeHintType
/**
* Hint payload. For `type: 'plugin'`: a `name@marketplace` slug
* matching the form accepted by `parsePluginIdentifier`.
*/
value: string
/**
* First token of the shell command that produced this hint. Shown in the
* install prompt so the user can spot a mismatch between the tool that
* emitted the hint and the plugin it recommends.
*/
sourceCommand: string
}
/** Spec versions this harness understands. */
const SUPPORTED_VERSIONS = new Set([1])
/** Hint types this harness understands at the supported versions. */
const SUPPORTED_TYPES = new Set<string>(['plugin'])
/**
* Outer tag match. Anchored to whole lines (multiline mode) so that a
* hint marker buried in a larger line — e.g. a log statement quoting the
* tag — is ignored. Leading and trailing whitespace on the line is
* tolerated since some SDKs pad stderr.
*/
const HINT_TAG_RE = /^[ \t]*<claude-code-hint\s+([^>]*?)\s*\/>[ \t]*$/gm
/**
* Attribute matcher. Accepts `key="value"` and `key=value` (terminated by
* whitespace or `/>` closing sequence). Values containing whitespace or `"` must use the quoted
* form. The quoted form does not support escape sequences; raise the spec
* version if that becomes necessary.
*/
const ATTR_RE = /(\w+)=(?:"([^"]*)"|([^\s/>]+))/g
/**
* Scan shell tool output for hint tags, returning the parsed hints and
* the output with hint lines removed. The stripped output is what the
* model sees — hints are a harness-only side channel.
*
* @param output - Raw command output (stdout with stderr interleaved).
* @param command - The command that produced the output; its first
* whitespace-separated token is recorded as `sourceCommand`.
*/
export function extractClaudeCodeHints(
output: string,
command: string,
): { hints: ClaudeCodeHint[]; stripped: string } {
// Fast path: no tag open sequence → no work, no allocation.
if (!output.includes('<claude-code-hint')) {
return { hints: [], stripped: output }
}
const sourceCommand = firstCommandToken(command)
const hints: ClaudeCodeHint[] = []
const stripped = output.replace(HINT_TAG_RE, rawLine => {
const attrs = parseAttrs(rawLine)
const v = Number(attrs.v)
const type = attrs.type
const value = attrs.value
if (!SUPPORTED_VERSIONS.has(v)) {
logForDebugging(
`[claudeCodeHints] dropped hint with unsupported v=${attrs.v}`,
)
return ''
}
if (!type || !SUPPORTED_TYPES.has(type)) {
logForDebugging(
`[claudeCodeHints] dropped hint with unsupported type=${type}`,
)
return ''
}
if (!value) {
logForDebugging('[claudeCodeHints] dropped hint with empty value')
return ''
}
hints.push({ v, type: type as ClaudeCodeHintType, value, sourceCommand })
return ''
})
// Dropping a matched line leaves a blank line (the surrounding newlines
// remain). Collapse runs of blank lines introduced by the replace so the
// model-visible output doesn't grow vertical whitespace.
const collapsed =
hints.length > 0 || stripped !== output
? stripped.replace(/\n{3,}/g, '\n\n')
: stripped
return { hints, stripped: collapsed }
}
function parseAttrs(tagBody: string): Record<string, string> {
const attrs: Record<string, string> = {}
for (const m of tagBody.matchAll(ATTR_RE)) {
attrs[m[1]!] = m[2] ?? m[3] ?? ''
}
return attrs
}
function firstCommandToken(command: string): string {
const trimmed = command.trim()
const spaceIdx = trimmed.search(/\s/)
return spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx)
}
// ============================================================================
// Pending-hint store (useSyncExternalStore interface)
//
// Single-slot: write wins if the slot is already full (a CLI that emits on
// every invocation would otherwise pile up). The dialog is shown at most
// once per session; after that, setPendingHint becomes a no-op.
//
// Callers should gate before writing (installed? already shown? cap hit?) —
// see maybeRecordPluginHint in hintRecommendation.ts for the plugin-type
// gate. This module stays plugin-agnostic so future hint types can reuse
// the same store.
// ============================================================================
let pendingHint: ClaudeCodeHint | null = null
let shownThisSession = false
const pendingHintChanged = createSignal()
const notify = pendingHintChanged.emit
/** Raw store write. Callers should gate first (see module comment). */
export function setPendingHint(hint: ClaudeCodeHint): void {
if (shownThisSession) return
pendingHint = hint
notify()
}
/** Clear the slot without flipping the session flag — for rejected hints. */
export function clearPendingHint(): void {
if (pendingHint !== null) {
pendingHint = null
notify()
}
}
/** Flip the once-per-session flag. Call only when a dialog is actually shown. */
export function markShownThisSession(): void {
shownThisSession = true
}
export const subscribeToPendingHint = pendingHintChanged.subscribe
export function getPendingHintSnapshot(): ClaudeCodeHint | null {
return pendingHint
}
export function hasShownHintThisSession(): boolean {
return shownThisSession
}
/** Test-only reset. */
export function _resetClaudeCodeHintStore(): void {
pendingHint = null
shownThisSession = false
}
export const _test = {
parseAttrs,
firstCommandToken,
}