@sagmans/dsh-plannotator 0.1.0

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/dist/config.js ADDED
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Plugin configuration: the row's `config` block, its defaults, and the two
3
+ * paths that are derived rather than configured.
4
+ *
5
+ * Defaults are data, not schema literals, because the loader validates through
6
+ * {@link Config} while a hand-built or re-normalized value goes through
7
+ * {@link normalizeConfig} — one table keeps the two from disagreeing.
8
+ *
9
+ * @module dsh-plannotator/config
10
+ */
11
+ import { homedir } from 'node:os';
12
+ import { join } from 'node:path';
13
+ import z from '@deepseek-ai/schemastery';
14
+ import { DATA_DIR_ENV, DATA_DIR_FALLBACK_NAME, DATA_DIR_NAMESPACE, DEFAULT_MAX_INPUT_BYTES, PLANS_SUBDIR, } from "./constants.js";
15
+ /** How approved-plan notes are treated: forwarded as guidance, or dropped. */
16
+ export const APPROVE_NOTES_MODES = ['steer', 'ignore'];
17
+ /** The values a profile gets when it sets nothing. */
18
+ export const CONFIG_DEFAULTS = {
19
+ binary: '',
20
+ dataDir: '',
21
+ // A browser tab left open is the human's decision; a timer that silently
22
+ // declines their review would be the plugin answering for them.
23
+ reviewTimeoutMs: 0,
24
+ tailscale: false,
25
+ steerFeedback: true,
26
+ approveNotes: 'steer',
27
+ allowUntrustedBinary: false,
28
+ maxInputBytes: DEFAULT_MAX_INPUT_BYTES,
29
+ };
30
+ /** Loader-facing schema; every field defaulted so a row config may name any subset. */
31
+ export const Config = z.object({
32
+ binary: z.string().default(CONFIG_DEFAULTS.binary),
33
+ dataDir: z.string().default(CONFIG_DEFAULTS.dataDir),
34
+ reviewTimeoutMs: z.natural().default(CONFIG_DEFAULTS.reviewTimeoutMs),
35
+ tailscale: z.boolean().default(CONFIG_DEFAULTS.tailscale),
36
+ steerFeedback: z.boolean().default(CONFIG_DEFAULTS.steerFeedback),
37
+ approveNotes: z.union([z.const('steer'), z.const('ignore')]).default(CONFIG_DEFAULTS.approveNotes),
38
+ allowUntrustedBinary: z.boolean().default(CONFIG_DEFAULTS.allowUntrustedBinary),
39
+ maxInputBytes: z.natural().default(CONFIG_DEFAULTS.maxInputBytes),
40
+ });
41
+ function isRecord(value) {
42
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
43
+ }
44
+ function readBoolean(raw, key) {
45
+ const value = raw[key];
46
+ return typeof value === 'boolean' ? value : CONFIG_DEFAULTS[key];
47
+ }
48
+ function readCount(raw, key) {
49
+ const value = raw[key];
50
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
51
+ ? value
52
+ : CONFIG_DEFAULTS[key];
53
+ }
54
+ /**
55
+ * Apply defaults to a config object the loader did not validate.
56
+ *
57
+ * The loader validates the row's config, but a directly-imported `apply` (tests,
58
+ * an embedding host) gets whatever the caller passed; a missing field would
59
+ * otherwise read as `undefined` and turn into the string "undefined" on a
60
+ * command line.
61
+ *
62
+ * @param raw - candidate config, of unknown provenance.
63
+ * @returns a complete config; unknown or malformed fields fall back to defaults.
64
+ */
65
+ export function normalizeConfig(raw) {
66
+ if (!isRecord(raw))
67
+ return CONFIG_DEFAULTS;
68
+ const approveNotes = raw['approveNotes'];
69
+ const steerOrIgnore = typeof approveNotes === 'string' &&
70
+ APPROVE_NOTES_MODES.includes(approveNotes)
71
+ ? approveNotes
72
+ : CONFIG_DEFAULTS.approveNotes;
73
+ return {
74
+ binary: typeof raw['binary'] === 'string' ? raw['binary'] : CONFIG_DEFAULTS.binary,
75
+ dataDir: typeof raw['dataDir'] === 'string' ? raw['dataDir'] : CONFIG_DEFAULTS.dataDir,
76
+ reviewTimeoutMs: readCount(raw, 'reviewTimeoutMs'),
77
+ tailscale: readBoolean(raw, 'tailscale'),
78
+ steerFeedback: readBoolean(raw, 'steerFeedback'),
79
+ approveNotes: steerOrIgnore,
80
+ allowUntrustedBinary: readBoolean(raw, 'allowUntrustedBinary'),
81
+ maxInputBytes: readCount(raw, 'maxInputBytes'),
82
+ };
83
+ }
84
+ /**
85
+ * Resolve the directory plan snapshots are written under.
86
+ *
87
+ * Config outranks the environment because a profile can pin a location the
88
+ * reader chose, while the environment is how a one-off run redirects it.
89
+ *
90
+ * @param config - resolved plugin config.
91
+ * @param env - process environment.
92
+ * @param home - the user's home directory.
93
+ * @returns the absolute data directory (it may not exist yet).
94
+ */
95
+ export function resolveDataDir(config, env, home = homedir()) {
96
+ if (config.dataDir !== '')
97
+ return config.dataDir;
98
+ const fromEnv = env[DATA_DIR_ENV];
99
+ if (typeof fromEnv === 'string' && fromEnv !== '')
100
+ return fromEnv;
101
+ return join(home, DATA_DIR_FALLBACK_NAME);
102
+ }
103
+ /**
104
+ * Resolve the directory plan snapshots are written into.
105
+ *
106
+ * One path per session is what lets the CLI's own plan history and diff work:
107
+ * a resubmitted plan overwrites the same document, so the browser can show what
108
+ * changed since the last review.
109
+ *
110
+ * @param dataDir - the resolved data directory.
111
+ * @returns the directory holding this plugin's plan snapshots.
112
+ */
113
+ export function resolvePlansDir(dataDir) {
114
+ return join(dataDir, DATA_DIR_NAMESPACE, PLANS_SUBDIR);
115
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Values every other module agrees on.
3
+ *
4
+ * They live here rather than inline because three call sites share each one:
5
+ * the argv builders, the decision mapper, and the tests that pin the CLI
6
+ * contract. A drift between them would be a review that silently reports the
7
+ * wrong verdict.
8
+ *
9
+ * @module dsh-plannotator/constants
10
+ */
11
+ /** Stable Loader identity: the profile patch row id, the plugin name, and the log prefix. */
12
+ export declare const PLUGIN_NAME = "plannotator";
13
+ /** Names the plugin owns in the harness' human-command registry. */
14
+ export declare const COMMAND_PLAN = "plannotator-plan";
15
+ export declare const COMMAND_REVIEW = "plannotator-review";
16
+ export declare const COMMAND_ANNOTATE = "plannotator-annotate";
17
+ export declare const COMMAND_LAST = "plannotator-last";
18
+ /** Environment overrides the CLI itself documents; they outrank nothing but config. */
19
+ export declare const BINARY_ENV = "PLANNOTATOR_BIN";
20
+ export declare const DATA_DIR_ENV = "PLANNOTATOR_DATA_DIR";
21
+ /** Where plan snapshots go when neither config nor environment names a data directory. */
22
+ export declare const DATA_DIR_FALLBACK_NAME = ".plannotator";
23
+ /**
24
+ * Plan snapshots live under a namespaced subdirectory because the data
25
+ * directory is the CLI's own: writing beside its `plans/` archive would put two
26
+ * different keying schemes in one tree.
27
+ */
28
+ export declare const DATA_DIR_NAMESPACE = "dsh";
29
+ export declare const PLANS_SUBDIR = "plans";
30
+ /** CLI subcommands this plugin drives. */
31
+ export declare const CLI_ANNOTATE = "annotate";
32
+ export declare const CLI_REVIEW = "review";
33
+ export declare const CLI_ANNOTATE_LAST = "annotate-last";
34
+ /** CLI flags with a fixed meaning; the same spelling appears in the docs and the tests. */
35
+ export declare const FLAG_GATE = "--gate";
36
+ export declare const FLAG_JSON = "--json";
37
+ export declare const FLAG_REQUIRE_APPROVAL = "--require-approval";
38
+ export declare const FLAG_TAILSCALE = "--tailscale";
39
+ export declare const FLAG_STDIN = "--stdin";
40
+ export declare const FLAG_BASE = "--base";
41
+ export declare const FLAG_DIFF_TYPE = "--diff-type";
42
+ export declare const FLAG_GIT = "--git";
43
+ export declare const FLAG_GITBUTLER = "--gitbutler";
44
+ export declare const FLAG_LOCAL = "--local";
45
+ export declare const FLAG_NO_LOCAL = "--no-local";
46
+ export declare const FLAG_NO_GIT_REMOTE_CHECK = "--no-git-remote-check";
47
+ export declare const FLAG_MARKDOWN = "--markdown";
48
+ export declare const FLAG_NO_JINA = "--no-jina";
49
+ export declare const FLAG_APP = "--app";
50
+ export declare const FLAG_STATIC = "--static";
51
+ export declare const FLAG_RENDER_HTML = "--render-html";
52
+ /**
53
+ * The harness tool whose arguments hold the newest plan.
54
+ *
55
+ * `exit_plan_mode` is registered by `@deepseek-ai/dsh-plan-mode` and stays
56
+ * registered while plan mode is inactive, so the last call is also the last
57
+ * plan a reader saw — which is exactly what an on-demand review wants.
58
+ */
59
+ export declare const EXIT_PLAN_MODE_TOOL = "exit_plan_mode";
60
+ /** The `approve` option label the plan-mode review declares; read from the request, never assumed. */
61
+ export declare const PLAN_DECLINE_FALLBACK_LABEL = "Keep planning";
62
+ /** Strict-gate exit codes the `annotate` command publishes under `--require-approval`. */
63
+ export declare const EXIT_APPROVED = 0;
64
+ export declare const EXIT_NOT_APPROVED = 1;
65
+ export declare const EXIT_GATE_FAILURE = 2;
66
+ /** Decision vocabulary shared by every plannotator surface. */
67
+ export declare const DECISION_APPROVED = "approved";
68
+ export declare const DECISION_ANNOTATED = "annotated";
69
+ export declare const DECISION_DISMISSED = "dismissed";
70
+ /**
71
+ * Cap on each captured stream.
72
+ *
73
+ * A review's stdout is one JSON record, but a failing CLI can print an
74
+ * arbitrarily long trace; keeping all of it would let a subprocess decide this
75
+ * process' memory. The tail is what a human reads, so the tail is what survives.
76
+ */
77
+ export declare const STREAM_CAP_BYTES: number;
78
+ /** How much of a failed run's stderr a command notice quotes. */
79
+ export declare const STDERR_TAIL_CHARS = 400;
80
+ /** Grace between SIGTERM and SIGKILL when a review is cancelled or times out. */
81
+ export declare const KILL_GRACE_MS = 2000;
82
+ /**
83
+ * Bound on text handed to a review session before it is written to disk.
84
+ *
85
+ * The CLI refuses files over 2 MB on its own; stopping earlier keeps a
86
+ * pathological transcript from being materialized at all.
87
+ */
88
+ export declare const DEFAULT_MAX_INPUT_BYTES: number;
89
+ /** Longest session-id fragment used in a snapshot filename. */
90
+ export declare const SESSION_SEGMENT_MAX_CHARS = 120;
91
+ /** Permissions for the snapshot file and the directory holding it. */
92
+ export declare const SNAPSHOT_FILE_MODE = 384;
93
+ export declare const SNAPSHOT_DIR_MODE = 448;
94
+ /** Report text a reviewer's own words are framed with before they reach the model. */
95
+ export declare const FEEDBACK_PREFIX = "[plannotator]";
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Values every other module agrees on.
3
+ *
4
+ * They live here rather than inline because three call sites share each one:
5
+ * the argv builders, the decision mapper, and the tests that pin the CLI
6
+ * contract. A drift between them would be a review that silently reports the
7
+ * wrong verdict.
8
+ *
9
+ * @module dsh-plannotator/constants
10
+ */
11
+ /** Stable Loader identity: the profile patch row id, the plugin name, and the log prefix. */
12
+ export const PLUGIN_NAME = 'plannotator';
13
+ /** Names the plugin owns in the harness' human-command registry. */
14
+ export const COMMAND_PLAN = 'plannotator-plan';
15
+ export const COMMAND_REVIEW = 'plannotator-review';
16
+ export const COMMAND_ANNOTATE = 'plannotator-annotate';
17
+ export const COMMAND_LAST = 'plannotator-last';
18
+ /** Environment overrides the CLI itself documents; they outrank nothing but config. */
19
+ export const BINARY_ENV = 'PLANNOTATOR_BIN';
20
+ export const DATA_DIR_ENV = 'PLANNOTATOR_DATA_DIR';
21
+ /** Where plan snapshots go when neither config nor environment names a data directory. */
22
+ export const DATA_DIR_FALLBACK_NAME = '.plannotator';
23
+ /**
24
+ * Plan snapshots live under a namespaced subdirectory because the data
25
+ * directory is the CLI's own: writing beside its `plans/` archive would put two
26
+ * different keying schemes in one tree.
27
+ */
28
+ export const DATA_DIR_NAMESPACE = 'dsh';
29
+ export const PLANS_SUBDIR = 'plans';
30
+ /** CLI subcommands this plugin drives. */
31
+ export const CLI_ANNOTATE = 'annotate';
32
+ export const CLI_REVIEW = 'review';
33
+ export const CLI_ANNOTATE_LAST = 'annotate-last';
34
+ /** CLI flags with a fixed meaning; the same spelling appears in the docs and the tests. */
35
+ export const FLAG_GATE = '--gate';
36
+ export const FLAG_JSON = '--json';
37
+ export const FLAG_REQUIRE_APPROVAL = '--require-approval';
38
+ export const FLAG_TAILSCALE = '--tailscale';
39
+ export const FLAG_STDIN = '--stdin';
40
+ export const FLAG_BASE = '--base';
41
+ export const FLAG_DIFF_TYPE = '--diff-type';
42
+ export const FLAG_GIT = '--git';
43
+ export const FLAG_GITBUTLER = '--gitbutler';
44
+ export const FLAG_LOCAL = '--local';
45
+ export const FLAG_NO_LOCAL = '--no-local';
46
+ export const FLAG_NO_GIT_REMOTE_CHECK = '--no-git-remote-check';
47
+ export const FLAG_MARKDOWN = '--markdown';
48
+ export const FLAG_NO_JINA = '--no-jina';
49
+ export const FLAG_APP = '--app';
50
+ export const FLAG_STATIC = '--static';
51
+ export const FLAG_RENDER_HTML = '--render-html';
52
+ /**
53
+ * The harness tool whose arguments hold the newest plan.
54
+ *
55
+ * `exit_plan_mode` is registered by `@deepseek-ai/dsh-plan-mode` and stays
56
+ * registered while plan mode is inactive, so the last call is also the last
57
+ * plan a reader saw — which is exactly what an on-demand review wants.
58
+ */
59
+ export const EXIT_PLAN_MODE_TOOL = 'exit_plan_mode';
60
+ /** The `approve` option label the plan-mode review declares; read from the request, never assumed. */
61
+ export const PLAN_DECLINE_FALLBACK_LABEL = 'Keep planning';
62
+ /** Strict-gate exit codes the `annotate` command publishes under `--require-approval`. */
63
+ export const EXIT_APPROVED = 0;
64
+ export const EXIT_NOT_APPROVED = 1;
65
+ export const EXIT_GATE_FAILURE = 2;
66
+ /** Decision vocabulary shared by every plannotator surface. */
67
+ export const DECISION_APPROVED = 'approved';
68
+ export const DECISION_ANNOTATED = 'annotated';
69
+ export const DECISION_DISMISSED = 'dismissed';
70
+ /**
71
+ * Cap on each captured stream.
72
+ *
73
+ * A review's stdout is one JSON record, but a failing CLI can print an
74
+ * arbitrarily long trace; keeping all of it would let a subprocess decide this
75
+ * process' memory. The tail is what a human reads, so the tail is what survives.
76
+ */
77
+ export const STREAM_CAP_BYTES = 1 << 20;
78
+ /** How much of a failed run's stderr a command notice quotes. */
79
+ export const STDERR_TAIL_CHARS = 400;
80
+ /** Grace between SIGTERM and SIGKILL when a review is cancelled or times out. */
81
+ export const KILL_GRACE_MS = 2000;
82
+ /**
83
+ * Bound on text handed to a review session before it is written to disk.
84
+ *
85
+ * The CLI refuses files over 2 MB on its own; stopping earlier keeps a
86
+ * pathological transcript from being materialized at all.
87
+ */
88
+ export const DEFAULT_MAX_INPUT_BYTES = 1 << 20;
89
+ /** Longest session-id fragment used in a snapshot filename. */
90
+ export const SESSION_SEGMENT_MAX_CHARS = 120;
91
+ /** Permissions for the snapshot file and the directory holding it. */
92
+ export const SNAPSHOT_FILE_MODE = 0o600;
93
+ export const SNAPSHOT_DIR_MODE = 0o700;
94
+ /** Report text a reviewer's own words are framed with before they reach the model. */
95
+ export const FEEDBACK_PREFIX = '[plannotator]';
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Turn a finished run into the reviewer's decision.
3
+ *
4
+ * The CLI publishes two different stdout contracts, and this module is the only
5
+ * place that knows which subcommand uses which:
6
+ *
7
+ * - `annotate` under `--gate --json --require-approval` reports the verdict as
8
+ * an exit code (0 approved, 1 not approved, 2 gate failure) and repeats it as
9
+ * one JSON record with an optional `feedback` string.
10
+ * - `review --json` reports `{ decision, message }` on stdout and attaches no
11
+ * meaning to the exit code.
12
+ *
13
+ * Everything downstream — steering, notices, error text — reads the
14
+ * {@link ReviewOutcome} produced here, so a change in one contract cannot leak
15
+ * into how another surface is reported.
16
+ *
17
+ * @module dsh-plannotator/decisions
18
+ */
19
+ import { DECISION_ANNOTATED, DECISION_APPROVED, DECISION_DISMISSED } from './constants.ts';
20
+ import type { RunResult } from './cli.ts';
21
+ /** The three verdicts every plannotator surface shares. */
22
+ export type ReviewDecision = typeof DECISION_APPROVED | typeof DECISION_ANNOTATED | typeof DECISION_DISMISSED;
23
+ /** One settled review. */
24
+ export interface ReviewOutcome {
25
+ readonly decision: ReviewDecision;
26
+ /** The reviewer's own words; empty when they approved or closed without writing any. */
27
+ readonly feedback: string;
28
+ }
29
+ /** Decision mapping either yields an outcome or the text explaining why it could not. */
30
+ export type OutcomeResult = {
31
+ readonly ok: true;
32
+ readonly outcome: ReviewOutcome;
33
+ } | {
34
+ readonly ok: false;
35
+ readonly error: string;
36
+ };
37
+ /**
38
+ * Read the JSON record the CLI prints.
39
+ *
40
+ * The whole stream is tried first because that is the documented shape; a
41
+ * per-line scan follows so a warning line printed before the record does not
42
+ * turn a decided review into an error.
43
+ *
44
+ * @param text - captured stdout.
45
+ * @returns the record, or `undefined` when stdout carries none.
46
+ */
47
+ export declare function readJsonRecord(text: string): Record<string, unknown> | undefined;
48
+ /**
49
+ * Map a strict `annotate` run (exit codes carry the verdict).
50
+ *
51
+ * @param result - the finished run.
52
+ * @returns the reviewer's decision, or why the gate failed.
53
+ */
54
+ export declare function outcomeFromAnnotate(result: RunResult): OutcomeResult;
55
+ /**
56
+ * Map an `annotate-last` run, which publishes no strict exit-code contract.
57
+ *
58
+ * The record is the verdict; only its absence is an error. An exit code alone
59
+ * cannot distinguish "the reviewer closed the tab" from "the CLI refused the
60
+ * input", so a run without a record is reported as a failure rather than
61
+ * guessed at.
62
+ *
63
+ * @param result - the finished run.
64
+ * @returns the reviewer's decision, or why no verdict was produced.
65
+ */
66
+ export declare function outcomeFromAnnotateLast(result: RunResult): OutcomeResult;
67
+ /**
68
+ * Map a `review --json` run.
69
+ *
70
+ * `message` is the CLI's rendered plaintext — approval framing and annotations
71
+ * together — so it is carried as feedback for every non-approval verdict and as
72
+ * guidance on an approval. The exit code is ignored on purpose: the documented
73
+ * contract for this subcommand puts the verdict in the record alone.
74
+ *
75
+ * @param result - the finished run.
76
+ * @returns the reviewer's decision, or why no verdict was produced.
77
+ */
78
+ export declare function outcomeFromReview(result: RunResult): OutcomeResult;
@@ -0,0 +1,170 @@
1
+ /**
2
+ * Turn a finished run into the reviewer's decision.
3
+ *
4
+ * The CLI publishes two different stdout contracts, and this module is the only
5
+ * place that knows which subcommand uses which:
6
+ *
7
+ * - `annotate` under `--gate --json --require-approval` reports the verdict as
8
+ * an exit code (0 approved, 1 not approved, 2 gate failure) and repeats it as
9
+ * one JSON record with an optional `feedback` string.
10
+ * - `review --json` reports `{ decision, message }` on stdout and attaches no
11
+ * meaning to the exit code.
12
+ *
13
+ * Everything downstream — steering, notices, error text — reads the
14
+ * {@link ReviewOutcome} produced here, so a change in one contract cannot leak
15
+ * into how another surface is reported.
16
+ *
17
+ * @module dsh-plannotator/decisions
18
+ */
19
+ import { DECISION_ANNOTATED, DECISION_APPROVED, DECISION_DISMISSED, EXIT_APPROVED, EXIT_GATE_FAILURE, EXIT_NOT_APPROVED, STDERR_TAIL_CHARS, } from "./constants.js";
20
+ function isRecord(value) {
21
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
22
+ }
23
+ /**
24
+ * Read the JSON record the CLI prints.
25
+ *
26
+ * The whole stream is tried first because that is the documented shape; a
27
+ * per-line scan follows so a warning line printed before the record does not
28
+ * turn a decided review into an error.
29
+ *
30
+ * @param text - captured stdout.
31
+ * @returns the record, or `undefined` when stdout carries none.
32
+ */
33
+ export function readJsonRecord(text) {
34
+ const trimmed = text.trim();
35
+ if (trimmed === '')
36
+ return undefined;
37
+ try {
38
+ const parsed = JSON.parse(trimmed);
39
+ return isRecord(parsed) ? parsed : undefined;
40
+ }
41
+ catch {
42
+ // Fall through to the line scan.
43
+ }
44
+ const lines = trimmed.split('\n');
45
+ for (let index = lines.length - 1; index >= 0; index -= 1) {
46
+ const line = lines[index]?.trim() ?? '';
47
+ if (!line.startsWith('{'))
48
+ continue;
49
+ try {
50
+ const parsed = JSON.parse(line);
51
+ if (isRecord(parsed))
52
+ return parsed;
53
+ }
54
+ catch {
55
+ // A line that is not a record is simply not the record.
56
+ }
57
+ }
58
+ return undefined;
59
+ }
60
+ /** Narrow a record's `decision` field, or `undefined` when it names no known verdict. */
61
+ function readDecision(record) {
62
+ const value = record?.['decision'];
63
+ if (value === DECISION_APPROVED || value === DECISION_ANNOTATED || value === DECISION_DISMISSED) {
64
+ return value;
65
+ }
66
+ return undefined;
67
+ }
68
+ /** Read a string field, treating anything else as absent. */
69
+ function readText(record, key) {
70
+ const value = record?.[key];
71
+ return typeof value === 'string' ? value : '';
72
+ }
73
+ /** The tail of a failed run's stderr, which is the part a notice can carry. */
74
+ function stderrTail(result) {
75
+ if (result.kind === 'spawn-failed')
76
+ return result.message;
77
+ const text = result.stderr.text.trim();
78
+ if (text === '')
79
+ return 'no diagnostic output';
80
+ return text.length > STDERR_TAIL_CHARS ? '…' + text.slice(-STDERR_TAIL_CHARS) : text;
81
+ }
82
+ /** The outcome of a run that never produced a verdict. */
83
+ function failure(result, context) {
84
+ if (result.kind === 'spawn-failed') {
85
+ return { ok: false, error: context + ': ' + result.message };
86
+ }
87
+ if (result.kind === 'timed-out') {
88
+ return { ok: false, error: context + ': the review timed out before a decision' };
89
+ }
90
+ if (result.kind === 'exited' && result.cancelled) {
91
+ return { ok: false, error: context + ': the review was cancelled' };
92
+ }
93
+ if (result.kind === 'signalled') {
94
+ return { ok: false, error: context + ': the review process was killed (' + String(result.signal) + ')' };
95
+ }
96
+ return { ok: false, error: context + ': ' + stderrTail(result) };
97
+ }
98
+ /**
99
+ * Map a strict `annotate` run (exit codes carry the verdict).
100
+ *
101
+ * @param result - the finished run.
102
+ * @returns the reviewer's decision, or why the gate failed.
103
+ */
104
+ export function outcomeFromAnnotate(result) {
105
+ if (result.kind === 'spawn-failed' || result.kind === 'signalled' || result.kind === 'timed-out') {
106
+ return failure(result, 'browser review did not finish');
107
+ }
108
+ if (result.cancelled)
109
+ return failure(result, 'browser review did not finish');
110
+ const record = readJsonRecord(result.stdout.text);
111
+ const feedback = readText(record, 'feedback');
112
+ if (result.code === EXIT_APPROVED)
113
+ return { ok: true, outcome: { decision: DECISION_APPROVED, feedback } };
114
+ if (result.code === EXIT_NOT_APPROVED) {
115
+ const decision = readDecision(record) ?? DECISION_ANNOTATED;
116
+ return { ok: true, outcome: { decision, feedback } };
117
+ }
118
+ if (result.code === EXIT_GATE_FAILURE) {
119
+ return { ok: false, error: 'the review could not start: ' + stderrTail(result) };
120
+ }
121
+ return failure(result, 'browser review failed (exit ' + String(result.code) + ')');
122
+ }
123
+ /**
124
+ * Map an `annotate-last` run, which publishes no strict exit-code contract.
125
+ *
126
+ * The record is the verdict; only its absence is an error. An exit code alone
127
+ * cannot distinguish "the reviewer closed the tab" from "the CLI refused the
128
+ * input", so a run without a record is reported as a failure rather than
129
+ * guessed at.
130
+ *
131
+ * @param result - the finished run.
132
+ * @returns the reviewer's decision, or why no verdict was produced.
133
+ */
134
+ export function outcomeFromAnnotateLast(result) {
135
+ if (result.kind !== 'exited' || result.cancelled) {
136
+ return failure(result, 'annotation did not finish');
137
+ }
138
+ const record = readJsonRecord(result.stdout.text);
139
+ const decision = readDecision(record);
140
+ if (decision === undefined) {
141
+ if (result.code === EXIT_APPROVED) {
142
+ // A record-less success is the CLI's plaintext close; nothing was written.
143
+ return { ok: true, outcome: { decision: DECISION_DISMISSED, feedback: '' } };
144
+ }
145
+ return failure(result, 'annotation did not finish (exit ' + String(result.code) + ')');
146
+ }
147
+ return { ok: true, outcome: { decision, feedback: readText(record, 'feedback') } };
148
+ }
149
+ /**
150
+ * Map a `review --json` run.
151
+ *
152
+ * `message` is the CLI's rendered plaintext — approval framing and annotations
153
+ * together — so it is carried as feedback for every non-approval verdict and as
154
+ * guidance on an approval. The exit code is ignored on purpose: the documented
155
+ * contract for this subcommand puts the verdict in the record alone.
156
+ *
157
+ * @param result - the finished run.
158
+ * @returns the reviewer's decision, or why no verdict was produced.
159
+ */
160
+ export function outcomeFromReview(result) {
161
+ if (result.kind !== 'exited' || result.cancelled) {
162
+ return failure(result, 'code review did not finish');
163
+ }
164
+ const record = readJsonRecord(result.stdout.text);
165
+ const decision = readDecision(record);
166
+ if (decision === undefined) {
167
+ return failure(result, 'code review did not finish (exit ' + String(result.code) + ')');
168
+ }
169
+ return { ok: true, outcome: { decision, feedback: readText(record, 'message') } };
170
+ }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Deliver a reviewer's words to the model.
3
+ *
4
+ * A command's result is rendered as one notice in the terminal surface, so it
5
+ * cannot itself be the feedback channel: the model would never see it. Steering
6
+ * is the harness seam that carries text into the conversation, and it is the
7
+ * same seam `/plan <message>` uses, so the model sees the reviewer as a person
8
+ * speaking rather than as a plugin mutating history.
9
+ *
10
+ * @module dsh-plannotator/feedback
11
+ */
12
+ import type { Agent } from '@deepseek-ai/dsh-agent';
13
+ import type { ReviewOutcome } from './decisions.ts';
14
+ /**
15
+ * Frame reviewer text so the model can attribute it.
16
+ *
17
+ * The prefix is the only provenance marker the model gets: without it, an
18
+ * annotation quoted from a reviewed document is indistinguishable from the
19
+ * reader's own instruction.
20
+ *
21
+ * @param target - what was reviewed, as the reviewer saw it.
22
+ * @param body - the reviewer's text.
23
+ * @returns the message body to steer.
24
+ */
25
+ export declare function frameFeedback(target: string, body: string): string;
26
+ /**
27
+ * Frame an approval that carried notes.
28
+ *
29
+ * @param target - what was reviewed.
30
+ * @param notes - the notes written alongside the approval.
31
+ * @returns the message body to steer.
32
+ */
33
+ export declare function frameApprovalNotes(target: string, notes: string): string;
34
+ /**
35
+ * Hand text to the agent as a steering message.
36
+ *
37
+ * Steering targets the nearest step boundary, and an idle driver opens a turn
38
+ * for it, so feedback lands whether the agent is mid-turn or waiting for input.
39
+ *
40
+ * @param agent - the agent whose session received the review.
41
+ * @param text - the framed message body.
42
+ */
43
+ export declare function steerText(agent: Agent, text: string): void;
44
+ /**
45
+ * Decide whether an outcome produces a message for the model, and which one.
46
+ *
47
+ * Approvals are the case that needs a policy: plannotator treats notes on an
48
+ * approval as guidance rather than a change request, and a profile may prefer
49
+ * to keep them out of the conversation entirely.
50
+ *
51
+ * @param outcome - the settled review.
52
+ * @param target - what was reviewed.
53
+ * @param approveNotes - whether approval notes are forwarded.
54
+ * @returns the message body, or `undefined` when nothing should be sent.
55
+ */
56
+ export declare function feedbackFor(outcome: ReviewOutcome, target: string, approveNotes: 'steer' | 'ignore'): string | undefined;
57
+ /** The plugin's log prefix, so a diagnostic names its origin. */
58
+ export declare const LOG_PREFIX = "plannotator";