dsh-marker 0.0.0-stage → 0.1.2
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/README.md +44 -2
- package/client.js +609 -0
- package/cordis.patch.yml +5 -0
- package/docs/DETAIL.md +45 -0
- package/icon.svg +8 -0
- package/index.js +204 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +59 -4
- package/src/bridge.js +494 -0
- package/src/discovery.js +428 -0
- package/src/endpoint.js +166 -0
- package/src/focus.js +204 -0
- package/src/locator.js +317 -0
- package/src/mentions.js +120 -0
- package/src/paths.js +52 -0
- package/src/presentation.js +255 -0
- package/src/protocol.js +610 -0
- package/src/queue.js +278 -0
- package/src/sessions.js +240 -0
- package/src/store.js +267 -0
- package/src/tools.js +392 -0
package/src/store.js
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Append-only annotation store.
|
|
3
|
+
*
|
|
4
|
+
* One JSONL file under `$DSH_HOME/annotations` holds every mutation as an
|
|
5
|
+
* event line; the in-memory map is a fold over those lines. Images never enter
|
|
6
|
+
* the log — only the attachment reference the host issued does.
|
|
7
|
+
*
|
|
8
|
+
* Events:
|
|
9
|
+
* { op: 'put', ts, seq, id, data: AnnotationRecord }
|
|
10
|
+
* { op: 'patch', ts, seq, id, data: Partial<AnnotationRecord> }
|
|
11
|
+
* { op: 'del', ts, seq, id }
|
|
12
|
+
* { op: 'img', ts, seq, id, ref: ImageAttachmentRef }
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
|
|
16
|
+
import { join } from 'node:path'
|
|
17
|
+
|
|
18
|
+
const LOG_NAME = 'queue.jsonl'
|
|
19
|
+
/** Compact once the log is both long and mostly superseded. */
|
|
20
|
+
const COMPACT_MIN_LINES = 2_000
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* @typedef {import('./protocol.js').AnnotationRecord} AnnotationRecord
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
export class AnnotationStore {
|
|
27
|
+
/**
|
|
28
|
+
* @param {{ dir: string, logger?: { debug: Function, warn: Function } }} options
|
|
29
|
+
*/
|
|
30
|
+
constructor({ dir, logger }) {
|
|
31
|
+
this.dir = dir
|
|
32
|
+
this.logger = logger ?? { debug() {}, warn() {} }
|
|
33
|
+
/** @type {Map<string, AnnotationRecord>} */
|
|
34
|
+
this.records = new Map()
|
|
35
|
+
/** @type {Map<string, any>} */
|
|
36
|
+
this.images = new Map()
|
|
37
|
+
this.seq = 0
|
|
38
|
+
this.lines = 0
|
|
39
|
+
this.ready = false
|
|
40
|
+
this.queue = Promise.resolve()
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
get file() {
|
|
44
|
+
return join(this.dir, LOG_NAME)
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Load the log into memory; safe to call once per activation. */
|
|
48
|
+
async load() {
|
|
49
|
+
await mkdir(this.dir, { recursive: true })
|
|
50
|
+
let text = ''
|
|
51
|
+
try {
|
|
52
|
+
text = await readFile(this.file, 'utf8')
|
|
53
|
+
} catch (error) {
|
|
54
|
+
if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error
|
|
55
|
+
}
|
|
56
|
+
for (const line of text.split('\n')) {
|
|
57
|
+
if (line.trim() === '') continue
|
|
58
|
+
this.lines += 1
|
|
59
|
+
let event
|
|
60
|
+
try {
|
|
61
|
+
event = JSON.parse(line)
|
|
62
|
+
} catch {
|
|
63
|
+
// A torn final line from a hard kill is expected; everything before it
|
|
64
|
+
// is still authoritative.
|
|
65
|
+
this.logger.warn('annotations: skipping an unparseable log line')
|
|
66
|
+
continue
|
|
67
|
+
}
|
|
68
|
+
this.#apply(event)
|
|
69
|
+
if (typeof event.seq === 'number' && event.seq > this.seq) this.seq = event.seq
|
|
70
|
+
}
|
|
71
|
+
this.ready = true
|
|
72
|
+
this.logger.debug(`annotations: loaded ${this.records.size} records from ${this.lines} lines`)
|
|
73
|
+
return this
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Serialize every mutation so append order matches seq order.
|
|
78
|
+
* @template T
|
|
79
|
+
* @param {() => Promise<T>} work
|
|
80
|
+
* @returns {Promise<T>}
|
|
81
|
+
*/
|
|
82
|
+
#serialize(work) {
|
|
83
|
+
const next = this.queue.then(work, work)
|
|
84
|
+
this.queue = next.then(
|
|
85
|
+
() => undefined,
|
|
86
|
+
() => undefined,
|
|
87
|
+
)
|
|
88
|
+
return next
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** @param {any} event */
|
|
92
|
+
#apply(event) {
|
|
93
|
+
switch (event.op) {
|
|
94
|
+
case 'put':
|
|
95
|
+
this.records.set(event.id, event.data)
|
|
96
|
+
break
|
|
97
|
+
case 'patch': {
|
|
98
|
+
const current = this.records.get(event.id)
|
|
99
|
+
if (current !== undefined) this.records.set(event.id, { ...current, ...event.data })
|
|
100
|
+
break
|
|
101
|
+
}
|
|
102
|
+
case 'del':
|
|
103
|
+
this.records.delete(event.id)
|
|
104
|
+
this.images.delete(event.id)
|
|
105
|
+
break
|
|
106
|
+
case 'img':
|
|
107
|
+
this.images.set(event.id, event.ref)
|
|
108
|
+
break
|
|
109
|
+
default:
|
|
110
|
+
break
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Append one event and fold it into memory.
|
|
116
|
+
* @param {Record<string, any>} event
|
|
117
|
+
*/
|
|
118
|
+
async #write(event) {
|
|
119
|
+
const full = { ...event, ts: new Date().toISOString(), seq: this.seq + 1 }
|
|
120
|
+
await appendFile(this.file, `${JSON.stringify(full)}\n`, 'utf8')
|
|
121
|
+
this.seq = full.seq
|
|
122
|
+
this.lines += 1
|
|
123
|
+
this.#apply(full)
|
|
124
|
+
return full.seq
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Insert or replace a record.
|
|
129
|
+
* @param {AnnotationRecord} record
|
|
130
|
+
* @returns {Promise<number>} the assigned seq
|
|
131
|
+
*/
|
|
132
|
+
put(record) {
|
|
133
|
+
return this.#serialize(() => this.#write({ op: 'put', id: record.id, data: record }))
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Merge fields into an existing record.
|
|
138
|
+
* @param {string} id
|
|
139
|
+
* @param {Partial<AnnotationRecord>} fields
|
|
140
|
+
* @returns {Promise<AnnotationRecord | undefined>}
|
|
141
|
+
*/
|
|
142
|
+
async patch(id, fields) {
|
|
143
|
+
if (!this.records.has(id)) return undefined
|
|
144
|
+
await this.#serialize(() => this.#write({ op: 'patch', id, data: fields }))
|
|
145
|
+
return this.records.get(id)
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* @param {string} id
|
|
150
|
+
* @returns {Promise<boolean>}
|
|
151
|
+
*/
|
|
152
|
+
async delete(id) {
|
|
153
|
+
if (!this.records.has(id)) return false
|
|
154
|
+
await this.#serialize(() => this.#write({ op: 'del', id }))
|
|
155
|
+
return true
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Remember the attachment reference for one annotation's crop.
|
|
160
|
+
* @param {string} id
|
|
161
|
+
* @param {any} ref
|
|
162
|
+
*/
|
|
163
|
+
setImage(id, ref) {
|
|
164
|
+
return this.#serialize(() => this.#write({ op: 'img', id, ref }))
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** @param {string} id */
|
|
168
|
+
get(id) {
|
|
169
|
+
return this.records.get(id)
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** @param {string} id */
|
|
173
|
+
image(id) {
|
|
174
|
+
return this.images.get(id)
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
get size() {
|
|
178
|
+
return this.records.size
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* @param {{ status?: string, url?: string, kind?: string, limit?: number }} [filter]
|
|
183
|
+
* @returns {AnnotationRecord[]}
|
|
184
|
+
*/
|
|
185
|
+
list(filter = {}) {
|
|
186
|
+
const status = filter.status ?? 'open'
|
|
187
|
+
const url = filter.url
|
|
188
|
+
const kind = filter.kind
|
|
189
|
+
const limit = Math.max(1, Math.min(200, filter.limit ?? 20))
|
|
190
|
+
/** @type {AnnotationRecord[]} */
|
|
191
|
+
const out = []
|
|
192
|
+
for (const record of this.records.values()) {
|
|
193
|
+
if (status !== 'all' && record.state !== status) continue
|
|
194
|
+
if (typeof url === 'string' && url !== '' && !matchesUrl(record.url, url)) continue
|
|
195
|
+
if (typeof kind === 'string' && record.anchor?.kind !== kind) continue
|
|
196
|
+
out.push(record)
|
|
197
|
+
}
|
|
198
|
+
out.sort((left, right) => String(right.updatedAt).localeCompare(String(left.updatedAt)))
|
|
199
|
+
return out.slice(0, limit)
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** @param {(record: AnnotationRecord) => boolean} predicate */
|
|
203
|
+
count(predicate) {
|
|
204
|
+
let total = 0
|
|
205
|
+
for (const record of this.records.values()) if (predicate(record)) total += 1
|
|
206
|
+
return total
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* Rewrite the log when most of its lines are superseded, keeping only the
|
|
211
|
+
* live projection. Atomic: a rename replaces the file in one step.
|
|
212
|
+
*/
|
|
213
|
+
async maybeCompact(force = false) {
|
|
214
|
+
if (this.lines < COMPACT_MIN_LINES) return false
|
|
215
|
+
const live = this.records.size + this.images.size
|
|
216
|
+
if (!force && this.lines <= live * 2) return false
|
|
217
|
+
return this.#serialize(async () => {
|
|
218
|
+
if (force && this.lines < COMPACT_MIN_LINES) return false
|
|
219
|
+
const lines = []
|
|
220
|
+
let seq = 0
|
|
221
|
+
for (const [id, record] of this.records) {
|
|
222
|
+
seq += 1
|
|
223
|
+
lines.push(JSON.stringify({ op: 'put', ts: new Date().toISOString(), seq, id, data: record }))
|
|
224
|
+
const ref = this.images.get(id)
|
|
225
|
+
if (ref !== undefined) {
|
|
226
|
+
seq += 1
|
|
227
|
+
lines.push(JSON.stringify({ op: 'img', ts: new Date().toISOString(), seq, id, ref }))
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
const temporary = `${this.file}.tmp`
|
|
231
|
+
await writeFile(temporary, lines.length === 0 ? '' : `${lines.join('\n')}\n`, 'utf8')
|
|
232
|
+
await rename(temporary, this.file)
|
|
233
|
+
this.lines = lines.length
|
|
234
|
+
this.seq = seq
|
|
235
|
+
this.logger.debug(`annotations: compacted to ${lines.length} lines`)
|
|
236
|
+
return true
|
|
237
|
+
})
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/** Wait for queued writes to settle (tests and shutdown). */
|
|
241
|
+
async flush() {
|
|
242
|
+
await this.queue
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Match a stored URL against a filter: exact, origin, pathname, or host
|
|
248
|
+
* substring. Deliberately forgiving because the caller may hold a URL with a
|
|
249
|
+
* different query string than the one recorded.
|
|
250
|
+
* @param {string} stored
|
|
251
|
+
* @param {string} filter
|
|
252
|
+
*/
|
|
253
|
+
export function matchesUrl(stored, filter) {
|
|
254
|
+
if (stored === filter) return true
|
|
255
|
+
try {
|
|
256
|
+
const left = new URL(stored)
|
|
257
|
+
const right = filter.includes('://') ? new URL(filter) : undefined
|
|
258
|
+
if (right !== undefined) {
|
|
259
|
+
if (left.origin !== right.origin) return false
|
|
260
|
+
if (right.pathname === '/' || right.pathname === '') return true
|
|
261
|
+
return left.pathname === right.pathname
|
|
262
|
+
}
|
|
263
|
+
return left.hostname.includes(filter) || left.pathname.includes(filter)
|
|
264
|
+
} catch {
|
|
265
|
+
return filter === '' ? true : stored.includes(filter)
|
|
266
|
+
}
|
|
267
|
+
}
|
package/src/tools.js
ADDED
|
@@ -0,0 +1,392 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Model-facing tools.
|
|
3
|
+
*
|
|
4
|
+
* Definitions are plain objects with raw JSON Schema: the plugin deliberately
|
|
5
|
+
* imports nothing from `@deepseek-ai/*` so it can be installed into any profile
|
|
6
|
+
* without bundling, and keeps working across harness releases that reshape
|
|
7
|
+
* their TypeScript-only helpers.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { LIMITS, STATES, describeAnchor, truncate } from './protocol.js'
|
|
11
|
+
|
|
12
|
+
/** @param {unknown} value */
|
|
13
|
+
function iso(value) {
|
|
14
|
+
return typeof value === 'string' ? value : new Date(/** @type {any} */ (value) ?? Date.now()).toISOString()
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Build the text envelope for one record. The structured half is JSON so a
|
|
19
|
+
* model can read exact anchors; the prose half says what the thing is.
|
|
20
|
+
* @param {any} record
|
|
21
|
+
* @param {{ includeRecord?: boolean }} [options]
|
|
22
|
+
*/
|
|
23
|
+
export function summarize(record, options = {}) {
|
|
24
|
+
const lines = [
|
|
25
|
+
`annotation ${record.id} [${record.state}] ${describeAnchor(record)}`,
|
|
26
|
+
`url: ${record.url}`,
|
|
27
|
+
...(record.title ? [`title: ${record.title}`] : []),
|
|
28
|
+
...(record.intent ? [`intent: ${record.intent}`] : []),
|
|
29
|
+
`comment: ${record.comment === '' ? '(empty)' : record.comment}`,
|
|
30
|
+
`created: ${iso(record.createdAt)}`,
|
|
31
|
+
...(record.resolution?.note ? [`resolution: ${record.resolution.note}`] : []),
|
|
32
|
+
]
|
|
33
|
+
if (options.includeRecord !== false) {
|
|
34
|
+
lines.push('', 'structured:', JSON.stringify(record, null, 2))
|
|
35
|
+
}
|
|
36
|
+
return lines.join('\n')
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @param {object} options
|
|
41
|
+
* @param {import('./store.js').AnnotationStore} options.store
|
|
42
|
+
* @param {ReturnType<import('./bridge.js').createBridge>} options.bridge
|
|
43
|
+
*/
|
|
44
|
+
export function createTools({ store, bridge }) {
|
|
45
|
+
/** @param {any} record */
|
|
46
|
+
function imageBlock(record) {
|
|
47
|
+
const ref = record?.host?.image ?? store.image(record?.id)
|
|
48
|
+
if (ref === undefined) return []
|
|
49
|
+
return [{ type: 'image', attachment: ref }]
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** @type {any[]} */
|
|
53
|
+
const tools = [
|
|
54
|
+
{
|
|
55
|
+
name: 'annotate_list',
|
|
56
|
+
description:
|
|
57
|
+
'List visual annotations the user left in their browser (text selections, DOM elements, or screen regions) ' +
|
|
58
|
+
'via the dsh-marker extension. Defaults to open annotations. Use this to discover what the user marked ' +
|
|
59
|
+
'before asking them to explain a page again.',
|
|
60
|
+
parameters: {
|
|
61
|
+
type: 'object',
|
|
62
|
+
properties: {
|
|
63
|
+
status: { type: 'string', enum: [...STATES, 'all'], description: 'Filter by state; default open.' },
|
|
64
|
+
url_filter: { type: 'string', description: 'Substring or full URL to narrow by page.' },
|
|
65
|
+
kind: { type: 'string', enum: ['selection', 'element', 'region'], description: 'Filter by anchor modality.' },
|
|
66
|
+
limit: { type: 'integer', minimum: 1, maximum: LIMITS.listLimit, description: 'Maximum rows; default 20.' },
|
|
67
|
+
},
|
|
68
|
+
additionalProperties: false,
|
|
69
|
+
},
|
|
70
|
+
output: {
|
|
71
|
+
schema: {
|
|
72
|
+
type: 'object',
|
|
73
|
+
required: ['count', 'items'],
|
|
74
|
+
additionalProperties: false,
|
|
75
|
+
properties: {
|
|
76
|
+
count: { type: 'integer' },
|
|
77
|
+
openCount: { type: 'integer' },
|
|
78
|
+
items: {
|
|
79
|
+
type: 'array',
|
|
80
|
+
items: {
|
|
81
|
+
type: 'object',
|
|
82
|
+
required: ['id', 'kind', 'state', 'url', 'preview'],
|
|
83
|
+
additionalProperties: false,
|
|
84
|
+
properties: {
|
|
85
|
+
id: { type: 'string' },
|
|
86
|
+
kind: { type: 'string' },
|
|
87
|
+
state: { type: 'string' },
|
|
88
|
+
url: { type: 'string' },
|
|
89
|
+
preview: { type: 'string' },
|
|
90
|
+
comment: { type: 'string' },
|
|
91
|
+
intent: { type: 'string' },
|
|
92
|
+
createdAt: { type: 'string' },
|
|
93
|
+
},
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
render: (_args, value) => {
|
|
99
|
+
const items = /** @type {any} */ (value).items
|
|
100
|
+
if (items.length === 0) return [{ type: 'text', text: 'No annotations match.' }]
|
|
101
|
+
const text = items
|
|
102
|
+
.map((item, index) => `${index + 1}. ${item.id} [${item.state}/${item.kind}] ${item.preview} — ${item.url}`)
|
|
103
|
+
.join('\n')
|
|
104
|
+
return [{ type: 'text', text: `${items.length} annotation(s):\n${text}` }]
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
execute(args) {
|
|
108
|
+
const query = /** @type {any} */ (args)
|
|
109
|
+
const records = store.list({
|
|
110
|
+
status: query.status ?? 'open',
|
|
111
|
+
url: query.url_filter,
|
|
112
|
+
kind: query.kind,
|
|
113
|
+
limit: query.limit ?? 20,
|
|
114
|
+
})
|
|
115
|
+
return Promise.resolve({
|
|
116
|
+
count: records.length,
|
|
117
|
+
openCount: store.count((record) => record.state === 'open'),
|
|
118
|
+
items: records.map((record) => ({
|
|
119
|
+
id: record.id,
|
|
120
|
+
kind: record.anchor?.kind ?? 'unknown',
|
|
121
|
+
state: record.state,
|
|
122
|
+
url: record.url,
|
|
123
|
+
preview: describeAnchor(record),
|
|
124
|
+
...(record.comment ? { comment: truncate(record.comment, 400) } : {}),
|
|
125
|
+
...(record.intent ? { intent: record.intent } : {}),
|
|
126
|
+
createdAt: iso(record.createdAt),
|
|
127
|
+
})),
|
|
128
|
+
})
|
|
129
|
+
},
|
|
130
|
+
},
|
|
131
|
+
|
|
132
|
+
{
|
|
133
|
+
name: 'annotate_get',
|
|
134
|
+
description:
|
|
135
|
+
'Read one annotation in full, including the cropped screenshot the user marked. Prefer this over annotate_list ' +
|
|
136
|
+
'when you are about to change or explain that specific spot: the image shows what the user saw, and the ' +
|
|
137
|
+
'structured anchor carries selectors, computed styles, and page facts.',
|
|
138
|
+
parameters: {
|
|
139
|
+
type: 'object',
|
|
140
|
+
properties: {
|
|
141
|
+
id: { type: 'string', description: 'Annotation id (an-yyyymmdd-xxxxxx).' },
|
|
142
|
+
latest: { type: 'boolean', description: 'Use the most recently updated annotation instead of id.' },
|
|
143
|
+
},
|
|
144
|
+
additionalProperties: false,
|
|
145
|
+
},
|
|
146
|
+
output: {
|
|
147
|
+
schema: {
|
|
148
|
+
type: 'object',
|
|
149
|
+
required: ['found'],
|
|
150
|
+
additionalProperties: false,
|
|
151
|
+
properties: {
|
|
152
|
+
found: { type: 'boolean' },
|
|
153
|
+
record: { type: 'object', additionalProperties: true },
|
|
154
|
+
hasImage: { type: 'boolean' },
|
|
155
|
+
},
|
|
156
|
+
},
|
|
157
|
+
render: (_args, value) => {
|
|
158
|
+
const typed = /** @type {any} */ (value)
|
|
159
|
+
if (typed.found !== true) return [{ type: 'text', text: 'No matching annotation.' }]
|
|
160
|
+
return [...imageBlock(typed.record), { type: 'text', text: summarize(typed.record) }]
|
|
161
|
+
},
|
|
162
|
+
},
|
|
163
|
+
execute(args) {
|
|
164
|
+
const query = /** @type {any} */ (args)
|
|
165
|
+
const record =
|
|
166
|
+
query.latest === true || typeof query.id !== 'string'
|
|
167
|
+
? store.list({ status: 'all', limit: 1 })[0]
|
|
168
|
+
: store.get(query.id)
|
|
169
|
+
if (record === undefined) return Promise.resolve({ found: false })
|
|
170
|
+
return Promise.resolve({
|
|
171
|
+
found: true,
|
|
172
|
+
record: { ...record, host: { imageId: record.host?.image?.attachmentId ?? null } },
|
|
173
|
+
hasImage: (record.host?.image ?? store.image(record.id)) !== undefined,
|
|
174
|
+
})
|
|
175
|
+
},
|
|
176
|
+
},
|
|
177
|
+
|
|
178
|
+
{
|
|
179
|
+
name: 'annotate_resolve',
|
|
180
|
+
description:
|
|
181
|
+
"Close the loop on an annotation: mark it resolved (or won't-fix), with a note the user sees on the page. " +
|
|
182
|
+
'The browser badge turns green immediately. Always include what you changed, so the note is useful later.',
|
|
183
|
+
parameters: {
|
|
184
|
+
type: 'object',
|
|
185
|
+
properties: {
|
|
186
|
+
id: { type: 'string', description: 'Annotation id.' },
|
|
187
|
+
status: { type: 'string', enum: [...STATES], description: 'New state; default resolved.' },
|
|
188
|
+
note: { type: 'string', description: 'Short note shown on the page badge.' },
|
|
189
|
+
files_touched: {
|
|
190
|
+
type: 'array',
|
|
191
|
+
items: { type: 'string' },
|
|
192
|
+
description: 'Workspace files changed for this annotation.',
|
|
193
|
+
},
|
|
194
|
+
},
|
|
195
|
+
required: ['id', 'note'],
|
|
196
|
+
additionalProperties: false,
|
|
197
|
+
},
|
|
198
|
+
output: {
|
|
199
|
+
schema: {
|
|
200
|
+
type: 'object',
|
|
201
|
+
required: ['ok', 'id', 'state'],
|
|
202
|
+
additionalProperties: false,
|
|
203
|
+
properties: { ok: { type: 'boolean' }, id: { type: 'string' }, state: { type: 'string' } },
|
|
204
|
+
},
|
|
205
|
+
render: (_args, value) => {
|
|
206
|
+
const typed = /** @type {any} */ (value)
|
|
207
|
+
return [
|
|
208
|
+
{ type: 'text', text: typed.ok ? `${typed.id} → ${typed.state}` : `${typed.id} could not be updated` },
|
|
209
|
+
]
|
|
210
|
+
},
|
|
211
|
+
},
|
|
212
|
+
async execute(args) {
|
|
213
|
+
const query = /** @type {any} */ (args)
|
|
214
|
+
const state = STATES.includes(query.status) ? query.status : 'resolved'
|
|
215
|
+
const record = await store.patch(query.id, {
|
|
216
|
+
state,
|
|
217
|
+
updatedAt: new Date().toISOString(),
|
|
218
|
+
resolution: {
|
|
219
|
+
by: 'agent',
|
|
220
|
+
note: String(query.note ?? ''),
|
|
221
|
+
...(Array.isArray(query.files_touched) ? { filesTouched: query.files_touched } : {}),
|
|
222
|
+
resolvedAt: Date.now(),
|
|
223
|
+
},
|
|
224
|
+
})
|
|
225
|
+
if (record === undefined) return { ok: false, id: query.id, state: 'missing' }
|
|
226
|
+
bridge.broadcast({ t: 'anno.event', type: 'updated', record, seq: store.seq })
|
|
227
|
+
return { ok: true, id: record.id, state: record.state }
|
|
228
|
+
},
|
|
229
|
+
},
|
|
230
|
+
|
|
231
|
+
{
|
|
232
|
+
name: 'annotate_delete',
|
|
233
|
+
description:
|
|
234
|
+
'Delete annotations outright instead of resolving them: the record, its crop, and its badge all go away. ' +
|
|
235
|
+
'Use this for noise the user never meant to keep (test marks, stale captures) — resolving leaves the mark on ' +
|
|
236
|
+
'their page, so prefer annotate_resolve when the work was actually done.',
|
|
237
|
+
parameters: {
|
|
238
|
+
type: 'object',
|
|
239
|
+
properties: {
|
|
240
|
+
ids: {
|
|
241
|
+
type: 'array',
|
|
242
|
+
items: { type: 'string' },
|
|
243
|
+
description: 'Annotation ids to delete.',
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
required: ['ids'],
|
|
247
|
+
additionalProperties: false,
|
|
248
|
+
},
|
|
249
|
+
output: {
|
|
250
|
+
schema: {
|
|
251
|
+
type: 'object',
|
|
252
|
+
required: ['deleted', 'missing'],
|
|
253
|
+
additionalProperties: false,
|
|
254
|
+
properties: {
|
|
255
|
+
deleted: { type: 'array', items: { type: 'string' } },
|
|
256
|
+
missing: { type: 'array', items: { type: 'string' } },
|
|
257
|
+
},
|
|
258
|
+
},
|
|
259
|
+
render: (_args, value) => {
|
|
260
|
+
const typed = /** @type {any} */ (value)
|
|
261
|
+
const parts = [`deleted ${typed.deleted.length}`]
|
|
262
|
+
if (typed.missing.length > 0) parts.push(`${typed.missing.length} not found`)
|
|
263
|
+
return [{ type: 'text', text: parts.join(', ') }]
|
|
264
|
+
},
|
|
265
|
+
},
|
|
266
|
+
async execute(args) {
|
|
267
|
+
const query = /** @type {any} */ (args)
|
|
268
|
+
const ids = Array.isArray(query.ids) ? query.ids.filter((id) => typeof id === 'string' && id !== '') : []
|
|
269
|
+
const deleted = []
|
|
270
|
+
const missing = []
|
|
271
|
+
for (const id of ids) {
|
|
272
|
+
const current = store.get(id)
|
|
273
|
+
if (current === undefined) {
|
|
274
|
+
missing.push(id)
|
|
275
|
+
continue
|
|
276
|
+
}
|
|
277
|
+
await store.delete(id)
|
|
278
|
+
// Same frame the overlay already listens to, so the badge disappears
|
|
279
|
+
// without waiting for the next snapshot refresh.
|
|
280
|
+
bridge.broadcast({ t: 'anno.event', type: 'deleted', record: { ...current, id }, seq: store.seq })
|
|
281
|
+
deleted.push(id)
|
|
282
|
+
}
|
|
283
|
+
return { deleted, missing }
|
|
284
|
+
},
|
|
285
|
+
},
|
|
286
|
+
|
|
287
|
+
{
|
|
288
|
+
name: 'annotate_pick',
|
|
289
|
+
description:
|
|
290
|
+
'Ask the user to point at something in their browser, then continue with the result. The page shows a banner ' +
|
|
291
|
+
'with your prompt; the user picks text, an element, or a region, and you receive the annotation with its crop ' +
|
|
292
|
+
'screenshot. Use this when a request is ambiguous about location ("this button", "that chart").',
|
|
293
|
+
parameters: {
|
|
294
|
+
type: 'object',
|
|
295
|
+
properties: {
|
|
296
|
+
prompt: { type: 'string', description: 'What to ask the user, shown in the browser banner.' },
|
|
297
|
+
mode: {
|
|
298
|
+
type: 'string',
|
|
299
|
+
enum: ['auto', 'selection', 'element', 'region'],
|
|
300
|
+
description: 'Restrict the gesture; default auto picks whichever the user performs.',
|
|
301
|
+
},
|
|
302
|
+
timeout_ms: {
|
|
303
|
+
type: 'integer',
|
|
304
|
+
minimum: 5000,
|
|
305
|
+
maximum: 900000,
|
|
306
|
+
description: 'How long to wait; default 120000.',
|
|
307
|
+
},
|
|
308
|
+
},
|
|
309
|
+
required: ['prompt'],
|
|
310
|
+
additionalProperties: false,
|
|
311
|
+
},
|
|
312
|
+
output: {
|
|
313
|
+
schema: {
|
|
314
|
+
type: 'object',
|
|
315
|
+
required: ['ok'],
|
|
316
|
+
additionalProperties: false,
|
|
317
|
+
properties: {
|
|
318
|
+
ok: { type: 'boolean' },
|
|
319
|
+
reason: { type: 'string' },
|
|
320
|
+
record: { type: 'object', additionalProperties: true },
|
|
321
|
+
},
|
|
322
|
+
},
|
|
323
|
+
timeoutMs: 900_000,
|
|
324
|
+
render: (_args, value) => {
|
|
325
|
+
const typed = /** @type {any} */ (value)
|
|
326
|
+
if (typed.ok !== true)
|
|
327
|
+
return [{ type: 'text', text: `The user did not pick a target: ${typed.reason ?? 'cancelled'}.` }]
|
|
328
|
+
return [...imageBlock(typed.record), { type: 'text', text: summarize(typed.record) }]
|
|
329
|
+
},
|
|
330
|
+
},
|
|
331
|
+
async execute(args, exec) {
|
|
332
|
+
const query = /** @type {any} */ (args)
|
|
333
|
+
const sessionId = exec?.agent?.session?.id
|
|
334
|
+
const result = await bridge.requestPick({
|
|
335
|
+
mode: query.mode,
|
|
336
|
+
prompt: String(query.prompt ?? 'Point at the relevant element'),
|
|
337
|
+
timeoutMs: query.timeout_ms,
|
|
338
|
+
sessionId: typeof sessionId === 'string' ? sessionId : undefined,
|
|
339
|
+
signal: exec?.signal,
|
|
340
|
+
})
|
|
341
|
+
if (result.ok !== true) return { ok: false, reason: result.reason }
|
|
342
|
+
const record = store.get(result.record.id) ?? result.record
|
|
343
|
+
return { ok: true, record: { ...record, host: { imageId: record.host?.image?.attachmentId ?? null } } }
|
|
344
|
+
},
|
|
345
|
+
},
|
|
346
|
+
|
|
347
|
+
{
|
|
348
|
+
name: 'annotate_clear',
|
|
349
|
+
description: 'Delete annotations in bulk, for example every resolved one after a cleanup pass.',
|
|
350
|
+
parameters: {
|
|
351
|
+
type: 'object',
|
|
352
|
+
properties: {
|
|
353
|
+
status: {
|
|
354
|
+
type: 'string',
|
|
355
|
+
enum: [...STATES, 'all'],
|
|
356
|
+
description: 'Which states to remove; default resolved.',
|
|
357
|
+
},
|
|
358
|
+
before_iso: { type: 'string', description: 'Only remove annotations created before this ISO timestamp.' },
|
|
359
|
+
},
|
|
360
|
+
additionalProperties: false,
|
|
361
|
+
},
|
|
362
|
+
output: {
|
|
363
|
+
schema: {
|
|
364
|
+
type: 'object',
|
|
365
|
+
required: ['removed'],
|
|
366
|
+
additionalProperties: false,
|
|
367
|
+
properties: { removed: { type: 'integer' } },
|
|
368
|
+
},
|
|
369
|
+
render: (_args, value) => [
|
|
370
|
+
{ type: 'text', text: `Removed ${/** @type {any} */ (value).removed} annotation(s).` },
|
|
371
|
+
],
|
|
372
|
+
},
|
|
373
|
+
async execute(args) {
|
|
374
|
+
const query = /** @type {any} */ (args)
|
|
375
|
+
const status = query.status ?? 'resolved'
|
|
376
|
+
const before = typeof query.before_iso === 'string' ? Date.parse(query.before_iso) : Number.NaN
|
|
377
|
+
const doomed = store.list({ status: 'all', limit: LIMITS.listLimit }).filter((record) => {
|
|
378
|
+
if (status !== 'all' && record.state !== status) return false
|
|
379
|
+
if (!Number.isNaN(before) && Date.parse(record.createdAt) >= before) return false
|
|
380
|
+
return true
|
|
381
|
+
})
|
|
382
|
+
for (const record of doomed) {
|
|
383
|
+
await store.delete(record.id)
|
|
384
|
+
bridge.broadcast({ t: 'anno.event', type: 'deleted', record, seq: store.seq })
|
|
385
|
+
}
|
|
386
|
+
return { removed: doomed.length }
|
|
387
|
+
},
|
|
388
|
+
},
|
|
389
|
+
]
|
|
390
|
+
|
|
391
|
+
return tools
|
|
392
|
+
}
|