Reference

Detector API versions

What each version of the detector API added, and everything the versions that still run offer.

A detector says which version it is written against by its import path, @wellactually/sdk/v4 or @wellactually/sdk/v3. Every host hands a detector the events of its own version for as long as that version runs, also when the principle is uploaded again. A new principle starts on the newest version. To move a principle to a newer one, change the import path in every file and let the compiler and the tests say what to adapt.

Version	Runs	What changed
4	Yes, current	Added `event.removed` on a write, `onDelete`, `DeleteEvent`, `RemovedLine`, and `removed` on a finding.
3	Yes	A handler per event in place of one `detect`.
2	No	Absolute paths, `relativePath`, `isNew`, `project`, and reading files through `node:fs`.
1	No	One `detect(ctx)` function.

Version 4#

Plugin 0.10.0 and newer. Everything version 3 offers, plus what an agent takes out of the code.

Added:

onDelete({ globs?, detect }) runs after the agent deleted a file. Its DeleteEvent has file as it was before it was deleted, and removed with every line of it.
event.removed on a WriteEvent: the lines the agent removed, as RemovedLine objects, each with the line it had before the change. A line the agent changed is removed as it was and written as it is now. It is empty when the plugin cannot tell what the file was before, as for a new file.
RemovedLine is { line, text, removed: true }. A handler may yield one as it is, and the agent is shown "removed line 3: ..." with its text.
removed: true on a Finding: its line and endLine name removed lines, by the line each had before, and its match occurs in them.
"delete" in EVENTS and in event.event.
In the tests: deleted(path, content), and edit(path, content, { removed, before }) for the text an edit took out of the file as it was.

Unchanged: every other handler, event, field and helper is the same as in version 3. The Detector API reference and the Test API describe version 4 in full.

Version 3#

Still run, so a principle on it keeps working without a change. It never sees removed lines or deletions: a deleted file does not run it, and its write events have no removed.

import { findUp, findWord, lineAt, matchesGlob, matchesGlobs, mentioned, onCommand, onOutput, onPrompt, onRead, onWrite } from "@wellactually/sdk/v3";
import type { CommandEvent, File, FileEvent, Finding, OutputEvent, PromptEvent, ReadEvent, TextFinding, WriteEvent, WrittenLine } from "@wellactually/sdk/v3";
import { command, detect, edit, output, prompt, read, source, write } from "@wellactually/sdk/v3/test";

Handlers#

Function	Runs	Takes
`onWrite(options)`	After the agent wrote or edited a file.	`{ globs?, detect(event: WriteEvent) }`
`onRead(options)`	After the agent read a file.	`{ globs?, detect(event: ReadEvent) }`
`onPrompt(options)`	When you sent a message, or the agent briefed a subagent.	`{ detect(event: PromptEvent) }`
`onCommand(options)`	Before a shell command runs.	`{ detect(event: CommandEvent) }`
`onOutput(options)`	After a shell command ran.	`{ detect(event: OutputEvent) }`

Only onWrite and onRead take globs.

Events#

Every event has event, text, lines and project. event is "write", "read", "prompt", "command" or "output".

Event	Adds
`WriteEvent`	`file: File`, `written: WrittenLine[]`
`ReadEvent`	`file: File`
`PromptEvent`	`cwd: string`
`CommandEvent`	`cwd: string`, `command: string`
`OutputEvent`	`cwd: string`, `command: string`

File is { path, relativePath, name, ext, content, lines, isNew }, and WrittenLine is { line, text }. A handler of onWrite may yield a WrittenLine as it is.

Findings#

A Finding is { line?, endLine?, match?, file?, depth? }, and a TextFinding, what onPrompt and onCommand yield, is the same without line and endLine.

Helpers#

findUp, mentioned, findWord, lineAt, matchesGlob, matchesGlobs and EVENTS, the same as in version 4 except that EVENTS has no "delete". A detector may also import node:fs and node:path.

Tests#

write(path, content, { isNew? }), edit(path, content, { written }), read(path, content), prompt(text), command(text), output(command, text), detect(event, { project? }) and source.