@venizia/vulcan 0.4.9 → 0.4.10-1
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 +1 -1
- package/base/hooks/guard-outside.ts +34 -15
- package/base/hooks/guard-remote-hosts.ts +13 -4
- package/base/rules.md +1 -0
- package/base/templates/board.html +315 -77
- package/package.json +3 -3
- package/src/board/common/constants.ts +10 -0
- package/src/board/common/types.ts +21 -0
- package/src/board/fold.ts +138 -6
- package/src/commands/help.command.ts +1 -1
- package/src/config/schema.ts +12 -8
- package/src/events/command.ts +41 -2
- package/src/events/common/constants.ts +9 -0
- package/src/events/common/types.ts +10 -0
- package/src/events/hook.ts +6 -1
- package/src/events/log.ts +56 -5
- package/src/hooks/host-pattern.ts +17 -0
- package/src/hooks/remote-hosts.ts +39 -7
- package/src/router.ts +4 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.10-1",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"bugs": {
|
|
@@ -44,8 +44,8 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@clack/prompts": "1.8.1",
|
|
47
|
-
"@venizia/vulcan-atlas": "0.4.
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.
|
|
47
|
+
"@venizia/vulcan-atlas": "0.4.10-1",
|
|
48
|
+
"@venizia/vulcan-okf": "0.4.10-1",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
@@ -25,6 +25,10 @@ export class BoardKinds {
|
|
|
25
25
|
static readonly RELEASE = 'release';
|
|
26
26
|
static readonly HANDOFF = 'handoff';
|
|
27
27
|
static readonly MSG = 'msg';
|
|
28
|
+
/** The line that names a flow: its summary is the title. */
|
|
29
|
+
static readonly FLOW = 'flow';
|
|
30
|
+
/** What the harness does around the work: a session starting or ending, a subagent stopping, a prompt waiting. */
|
|
31
|
+
static readonly AGENT = 'agent';
|
|
28
32
|
}
|
|
29
33
|
|
|
30
34
|
/** The stages of a flow, in the order of the page's strip. */
|
|
@@ -101,6 +105,12 @@ export class BoardConstants {
|
|
|
101
105
|
static readonly DATA_MARKER = '<!--BOARD_DATA-->';
|
|
102
106
|
static readonly GH_TIMEOUT_MS = 15_000;
|
|
103
107
|
static readonly GH_LIMIT = 30;
|
|
108
|
+
/** A `needs-owner` line whose whole summary is one of these is the harness waiting, not a person asking. */
|
|
109
|
+
static readonly HARNESS_ASKS = new Set<string>([
|
|
110
|
+
'idle_prompt',
|
|
111
|
+
'permission_prompt',
|
|
112
|
+
'elicitation_dialog',
|
|
113
|
+
]);
|
|
104
114
|
/** Kinds that mean someone did work on the flow, for the holder. */
|
|
105
115
|
static readonly WORK_KINDS = [
|
|
106
116
|
BoardKinds.ASSIGN,
|
|
@@ -19,10 +19,23 @@ export interface IBoardEvent {
|
|
|
19
19
|
stage: number;
|
|
20
20
|
actor: string;
|
|
21
21
|
to?: string;
|
|
22
|
+
/** A message the actor got, not sent (`msg-received`). */
|
|
23
|
+
incoming?: boolean;
|
|
24
|
+
/** Who sent a message the actor got, from a `from:<name>` ref. */
|
|
25
|
+
from?: string;
|
|
22
26
|
status?: string;
|
|
23
27
|
/** What a decision decided: `approve`, `park` or `reject`. */
|
|
24
28
|
choice?: string;
|
|
25
29
|
needsOwner?: boolean;
|
|
30
|
+
/** Agent plumbing: kept in the data, hidden by the page until "show all events". It never moves a flow. */
|
|
31
|
+
plumbing?: boolean;
|
|
32
|
+
/** This line names the flow: its summary is the title. */
|
|
33
|
+
isTitle?: boolean;
|
|
34
|
+
/** Only a title line has one: why the flow exists. */
|
|
35
|
+
why?: string;
|
|
36
|
+
/** Only a title line has them: what the flow is and what is left, and the next step. */
|
|
37
|
+
context?: string;
|
|
38
|
+
next?: string;
|
|
26
39
|
/** Which attempt this is: the nth run of one check, the nth review round. */
|
|
27
40
|
attempt?: number;
|
|
28
41
|
/** The check a CI line is about. */
|
|
@@ -36,6 +49,14 @@ export interface IBoardEvent {
|
|
|
36
49
|
export interface IBoardFlow {
|
|
37
50
|
id: string;
|
|
38
51
|
title: string;
|
|
52
|
+
/** The title came from a `flow` line; a flow without one shows its first line and "no title yet". */
|
|
53
|
+
named: boolean;
|
|
54
|
+
/** Why the flow exists, from the newest `flow` line that has one. */
|
|
55
|
+
why?: string;
|
|
56
|
+
/** What the flow is, what is done and what is left; from the same line as the title. */
|
|
57
|
+
context?: string;
|
|
58
|
+
/** The next step and who does it; from the same line as the title. */
|
|
59
|
+
next?: string;
|
|
39
60
|
repo?: string;
|
|
40
61
|
state: TBoardState;
|
|
41
62
|
/** Who has it now. */
|
package/src/board/fold.ts
CHANGED
|
@@ -20,6 +20,7 @@ const PR_NUMBER = /^#?(\d+)$/;
|
|
|
20
20
|
/** A `pr` line with this ref says the pull request was merged: `--ref merged:12`. */
|
|
21
21
|
const MERGED_REF = /^merged:#?(\d+)$/;
|
|
22
22
|
const TO_PREFIX = 'to:';
|
|
23
|
+
const FROM_PREFIX = 'from:';
|
|
23
24
|
/** Kinds that take the stage the flow is at when they happen: a message belongs to the stage it was sent in. */
|
|
24
25
|
const CARRY_KINDS: string[] = [BoardKinds.MSG, BoardKinds.NOTE];
|
|
25
26
|
|
|
@@ -72,19 +73,52 @@ export class BoardFold {
|
|
|
72
73
|
const decisions: Record<string, IBoardDecision> = {};
|
|
73
74
|
|
|
74
75
|
for (const [id, lines] of byFlow) {
|
|
75
|
-
|
|
76
|
+
// Plumbing (a session, a subagent, the harness waiting) and the lines that name the flow are carried along as
|
|
77
|
+
// lines of the flow; they never move it: not its state, stage, holder or last line. A `flow` line only sets the
|
|
78
|
+
// title and the reason, the newest by time winning.
|
|
79
|
+
const quiet = lines.filter((event) => event.plumbing === true || event.isTitle === true);
|
|
80
|
+
const core = lines.filter((event) => event.plumbing !== true && event.isTitle !== true);
|
|
81
|
+
const named = [...lines].sort(byTime).findLast((event) => event.isTitle === true);
|
|
82
|
+
|
|
83
|
+
if (core.length === 0) {
|
|
84
|
+
flows.push(BoardFold.quietFlow({ id, lines: quiet, named }));
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const events = BoardFold.prepare({ lines: core });
|
|
76
89
|
const decision = BoardFold.lastDecision({ events });
|
|
77
90
|
|
|
78
91
|
if (decision !== undefined) {
|
|
79
92
|
decisions[id] = decision;
|
|
80
93
|
}
|
|
81
94
|
|
|
82
|
-
|
|
95
|
+
const flow = BoardFold.flowOf({ id, events, owner: opts.owner });
|
|
96
|
+
|
|
97
|
+
flows.push({
|
|
98
|
+
...flow,
|
|
99
|
+
...BoardFold.headingOf({ named }),
|
|
100
|
+
...(quiet.length === 0
|
|
101
|
+
? {}
|
|
102
|
+
: { events: BoardFold.withQuiet({ events: flow.events, quiet }) }),
|
|
103
|
+
});
|
|
83
104
|
}
|
|
84
105
|
|
|
85
106
|
return { flows, decisions };
|
|
86
107
|
}
|
|
87
108
|
|
|
109
|
+
/**
|
|
110
|
+
* A `needs-owner` line the harness raised: the hook recorded the notification type (so a title such as "Claude
|
|
111
|
+
* needs your permission" is still the harness). A line without the field is judged by its summary alone, the way
|
|
112
|
+
* lines written before the field existed are: the name of a prompt, in any case.
|
|
113
|
+
*/
|
|
114
|
+
private static isHarnessAsk(opts: { line: IEvent }): boolean {
|
|
115
|
+
return (
|
|
116
|
+
opts.line.kind === EventKinds.NEEDS_OWNER &&
|
|
117
|
+
(opts.line.notification !== undefined ||
|
|
118
|
+
BoardConstants.HARNESS_ASKS.has(opts.line.summary.trim().toLowerCase()))
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
|
|
88
122
|
private static eventOf(opts: { line: IEvent }): IBoardEvent | undefined {
|
|
89
123
|
const { line } = opts;
|
|
90
124
|
const base = {
|
|
@@ -126,13 +160,50 @@ export class BoardFold {
|
|
|
126
160
|
|
|
127
161
|
case EventKinds.MSG_SENT:
|
|
128
162
|
case EventKinds.MSG_RECEIVED: {
|
|
129
|
-
const
|
|
163
|
+
const isIncoming = line.kind === EventKinds.MSG_RECEIVED;
|
|
164
|
+
// A received line has a sender, never a recipient: the page reads `to` as who the message went to.
|
|
165
|
+
const to =
|
|
166
|
+
!isIncoming && line.ref?.startsWith(TO_PREFIX)
|
|
167
|
+
? line.ref.slice(TO_PREFIX.length)
|
|
168
|
+
: undefined;
|
|
169
|
+
const from =
|
|
170
|
+
isIncoming && line.ref?.startsWith(FROM_PREFIX)
|
|
171
|
+
? line.ref.slice(FROM_PREFIX.length)
|
|
172
|
+
: undefined;
|
|
130
173
|
|
|
131
|
-
return {
|
|
174
|
+
return {
|
|
175
|
+
...base,
|
|
176
|
+
kind: BoardKinds.MSG,
|
|
177
|
+
stage: -1,
|
|
178
|
+
...(to === undefined ? {} : { to }),
|
|
179
|
+
...(isIncoming ? { incoming: true } : {}),
|
|
180
|
+
...(from === undefined || from === '' ? {} : { from }),
|
|
181
|
+
};
|
|
132
182
|
}
|
|
133
183
|
|
|
134
184
|
case EventKinds.NEEDS_OWNER: {
|
|
135
|
-
|
|
185
|
+
// The harness waiting for a prompt is not a person asking: it is shown only on request and never makes a flow wait.
|
|
186
|
+
return BoardFold.isHarnessAsk({ line })
|
|
187
|
+
? { ...base, kind: BoardKinds.NOTE, stage: -1, plumbing: true }
|
|
188
|
+
: { ...base, kind: BoardKinds.NOTE, stage: -1, needsOwner: true };
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
case EventKinds.FLOW: {
|
|
192
|
+
return {
|
|
193
|
+
...base,
|
|
194
|
+
kind: BoardKinds.FLOW,
|
|
195
|
+
stage: BoardStages.REQUEST,
|
|
196
|
+
isTitle: true,
|
|
197
|
+
...(line.why === undefined ? {} : { why: line.why }),
|
|
198
|
+
...(line.context === undefined ? {} : { context: line.context }),
|
|
199
|
+
...(line.next === undefined ? {} : { next: line.next }),
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
case EventKinds.SESSION_START:
|
|
204
|
+
case EventKinds.SESSION_STOP:
|
|
205
|
+
case EventKinds.SUBAGENT_STOP: {
|
|
206
|
+
return { ...base, kind: BoardKinds.AGENT, stage: -1, plumbing: true };
|
|
136
207
|
}
|
|
137
208
|
|
|
138
209
|
case EventKinds.DECISION: {
|
|
@@ -156,7 +227,7 @@ export class BoardFold {
|
|
|
156
227
|
const { agents, line } = opts;
|
|
157
228
|
const known = agents[line.actor];
|
|
158
229
|
|
|
159
|
-
if (line.kind === EventKinds.SUBAGENT_STOP) {
|
|
230
|
+
if (line.kind === EventKinds.SUBAGENT_STOP || BoardFold.isHarnessAsk({ line })) {
|
|
160
231
|
return;
|
|
161
232
|
}
|
|
162
233
|
|
|
@@ -261,6 +332,7 @@ export class BoardFold {
|
|
|
261
332
|
return {
|
|
262
333
|
id,
|
|
263
334
|
title: BoardFold.titleOf({ id, events }),
|
|
335
|
+
named: false,
|
|
264
336
|
...(repo === undefined ? {} : { repo }),
|
|
265
337
|
state,
|
|
266
338
|
holder: BoardFold.holderOf({ events, state, owner: opts.owner }),
|
|
@@ -278,6 +350,66 @@ export class BoardFold {
|
|
|
278
350
|
};
|
|
279
351
|
}
|
|
280
352
|
|
|
353
|
+
/** The heading a `flow` line gives: title, reason, context and next step. The newest line wins as a whole: a newer line that leaves a field out drops the old one, so no stale text outlives the line that wrote it. */
|
|
354
|
+
private static headingOf(opts: { named: IBoardEvent | undefined }): {
|
|
355
|
+
title?: string;
|
|
356
|
+
named: boolean;
|
|
357
|
+
why?: string;
|
|
358
|
+
context?: string;
|
|
359
|
+
next?: string;
|
|
360
|
+
} {
|
|
361
|
+
const { named } = opts;
|
|
362
|
+
|
|
363
|
+
return named === undefined
|
|
364
|
+
? { named: false }
|
|
365
|
+
: {
|
|
366
|
+
title: named.summary,
|
|
367
|
+
named: true,
|
|
368
|
+
...(named.why === undefined ? {} : { why: named.why }),
|
|
369
|
+
...(named.context === undefined ? {} : { context: named.context }),
|
|
370
|
+
...(named.next === undefined ? {} : { next: named.next }),
|
|
371
|
+
};
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* A flow with no line of work: only plumbing and `flow` lines. It is running (a closed group would hide what was just
|
|
376
|
+
* asked for), held by whoever wrote last; plumbing shows only when the page shows all events, a `flow` line always.
|
|
377
|
+
*/
|
|
378
|
+
private static quietFlow(opts: {
|
|
379
|
+
id: string;
|
|
380
|
+
lines: IBoardEvent[];
|
|
381
|
+
named: IBoardEvent | undefined;
|
|
382
|
+
}): IBoardFlow {
|
|
383
|
+
const events = [...opts.lines]
|
|
384
|
+
.sort(byTime)
|
|
385
|
+
.map((event) => ({ ...event, stage: BoardStages.REQUEST }));
|
|
386
|
+
const last = events[events.length - 1];
|
|
387
|
+
|
|
388
|
+
return {
|
|
389
|
+
id: opts.id,
|
|
390
|
+
title: opts.id,
|
|
391
|
+
...BoardFold.headingOf({ named: opts.named }),
|
|
392
|
+
state: BoardStates.RUNNING,
|
|
393
|
+
holder: last.actor,
|
|
394
|
+
stages: [BoardStages.REQUEST],
|
|
395
|
+
cur: BoardStages.REQUEST,
|
|
396
|
+
lastId: last.id,
|
|
397
|
+
ciRuns: 0,
|
|
398
|
+
reviewRounds: 0,
|
|
399
|
+
events,
|
|
400
|
+
};
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/** The quiet lines among the lines of a flow, each at the stage the flow was at when it happened. */
|
|
404
|
+
private static withQuiet(opts: { events: IBoardEvent[]; quiet: IBoardEvent[] }): IBoardEvent[] {
|
|
405
|
+
const placed = opts.quiet.map((event) => ({
|
|
406
|
+
...event,
|
|
407
|
+
stage: opts.events.findLast((core) => core.ts <= event.ts)?.stage ?? BoardStages.REQUEST,
|
|
408
|
+
}));
|
|
409
|
+
|
|
410
|
+
return [...opts.events, ...placed].sort(byTime);
|
|
411
|
+
}
|
|
412
|
+
|
|
281
413
|
private static stateOf(opts: {
|
|
282
414
|
events: IBoardEvent[];
|
|
283
415
|
live: IBoardEvent[];
|
|
@@ -39,7 +39,7 @@ Usage: bun x vulcan <command>
|
|
|
39
39
|
List the workspace packages a change touches (changed ones and what
|
|
40
40
|
depends on them) with the checks each has; template prints a CI file that
|
|
41
41
|
runs exactly those; exit 2 on bad input
|
|
42
|
-
event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | tail [--since <time>] [--json] [--dir <folder>]
|
|
42
|
+
event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | add --kind flow --flow F-n --title <text> [--why <text>] [--context <text>] [--next <text>] | tail [--since <time>] [--json] [--dir <folder>]
|
|
43
43
|
Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
|
|
44
44
|
read it; with events.log on, sync installs the Claude Code hooks that
|
|
45
45
|
write it; exit 2 on bad input
|
package/src/config/schema.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { isAbsolute } from 'node:path';
|
|
2
2
|
import { z } from 'zod';
|
|
3
3
|
import { LayoutFolder } from '../common/layout-folder.ts';
|
|
4
|
+
import { GuardDecisions } from '../hooks/common/constants.ts';
|
|
5
|
+
import { HostPatterns } from '../hooks/host-pattern.ts';
|
|
4
6
|
import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
5
7
|
import { AgentSignaturePolicies } from '../commit/common/index.ts';
|
|
6
8
|
import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
|
|
@@ -198,12 +200,9 @@ const OKF_RENDERER = z.union([
|
|
|
198
200
|
/** A host name, or a pattern whose only wildcard is `*`; a `$VAR` stands for a host the shell expands. Never a user, a path or a port. */
|
|
199
201
|
const REMOTE_HOST = z
|
|
200
202
|
.string()
|
|
201
|
-
.regex(
|
|
202
|
-
|
|
203
|
-
'a
|
|
204
|
-
)
|
|
205
|
-
.refine((value) => value.replaceAll('*', '').replaceAll('.', '') !== '', {
|
|
206
|
-
message: 'a pattern needs at least one literal character beyond * and .',
|
|
203
|
+
.regex(HostPatterns.SHAPE, 'a host name or a pattern with *, not a user, a path or a port')
|
|
204
|
+
.refine((value) => HostPatterns.hasLiteral({ value }), {
|
|
205
|
+
message: 'a pattern needs at least one letter or digit, not only * . - or _',
|
|
207
206
|
});
|
|
208
207
|
|
|
209
208
|
const VIZ_OUTPUT = '.agents/knowledge/viz.html';
|
|
@@ -343,7 +342,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
343
342
|
* The remote-host guard (W-04 in a project's own words): with this key set, sync registers a hook that
|
|
344
343
|
* asks before a Bash command reaches a host not listed here. `trusted` hosts are free; `readOnly`
|
|
345
344
|
* hosts pass only the strict read-only forms. Matching is by whole name or `*` pattern, never by substring.
|
|
346
|
-
* `localFile` is a gitignored list of personal
|
|
345
|
+
* `localFile` is a gitignored list of personal hosts, one per line: a host is trusted, `readonly: <host>` is a
|
|
346
|
+
* read-only host. Each entry follows the same rule as the lists above; one that does not is skipped.
|
|
347
347
|
*/
|
|
348
348
|
remoteHosts: z
|
|
349
349
|
.strictObject({
|
|
@@ -434,11 +434,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
434
434
|
* read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
|
|
435
435
|
* project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
|
|
436
436
|
* compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
|
|
437
|
-
* writes both to the manifest, where the hooks read them.
|
|
437
|
+
* writes both to the manifest, where the hooks read them. `outside` is what `guard-outside` does with a
|
|
438
|
+
* write outside the project: `ask` (the default) or `deny`. Where the agent runs in an auto mode an ask can be
|
|
439
|
+
* approved without the owner seeing it, so a project that wants the line held sets `deny`.
|
|
438
440
|
*/
|
|
439
441
|
guard: z
|
|
440
442
|
.strictObject({
|
|
441
443
|
toolOwnedPaths: z.array(z.string().min(1)).default([]),
|
|
444
|
+
outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
|
|
442
445
|
writes: z
|
|
443
446
|
.strictObject({
|
|
444
447
|
trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
|
|
@@ -449,6 +452,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
449
452
|
})
|
|
450
453
|
.default({
|
|
451
454
|
toolOwnedPaths: [],
|
|
455
|
+
outside: GuardDecisions.ASK,
|
|
452
456
|
writes: { trustedScripts: [], commands: [] },
|
|
453
457
|
git: { askPush: [] },
|
|
454
458
|
}),
|
package/src/events/command.ts
CHANGED
|
@@ -17,6 +17,7 @@ import { EventLog } from './log.ts';
|
|
|
17
17
|
import { EventSettings } from './settings.ts';
|
|
18
18
|
|
|
19
19
|
const USAGE = `usage: vulcan event add ${EventFlags.KIND} <kind> ${EventFlags.SUMMARY} <text> [${EventFlags.FLOW} F-n] [${EventFlags.REF} <ref>] [${EventFlags.STATUS} <${[...EventStatuses.SCHEME_SET].join('|')}>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
|
|
20
|
+
vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.FLOW} F-n ${EventFlags.TITLE} <text> [${EventFlags.WHY} <text>] [${EventFlags.CONTEXT} <text>] [${EventFlags.NEXT} <text>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
|
|
20
21
|
vulcan event tail [${EventFlags.SINCE} <time>] [${EventFlags.JSON}] [${EventFlags.DIR} <folder>]
|
|
21
22
|
kinds: ${[...EventKinds.SCHEME_SET].join(', ')}`;
|
|
22
23
|
|
|
@@ -83,7 +84,9 @@ export class EventCommand {
|
|
|
83
84
|
private static add(opts: { cwd: string; values: TFlagValues }): number {
|
|
84
85
|
const { values } = opts;
|
|
85
86
|
const kind = values[EventFlags.KIND];
|
|
86
|
-
const
|
|
87
|
+
const isFlow = kind === EventKinds.FLOW;
|
|
88
|
+
// A flow line is named by its title: the title is its summary, and `--summary` is not a second way to say it.
|
|
89
|
+
const summary = isFlow ? values[EventFlags.TITLE] : values[EventFlags.SUMMARY];
|
|
87
90
|
const flow = values[EventFlags.FLOW];
|
|
88
91
|
|
|
89
92
|
if (kind === undefined || !EventKinds.isValid(kind)) {
|
|
@@ -95,11 +98,38 @@ export class EventCommand {
|
|
|
95
98
|
}
|
|
96
99
|
|
|
97
100
|
if (summary === undefined || summary.trim() === '') {
|
|
98
|
-
process.stderr.write(
|
|
101
|
+
process.stderr.write(
|
|
102
|
+
`event: ${isFlow ? EventFlags.TITLE : EventFlags.SUMMARY} needs a short text\n`,
|
|
103
|
+
);
|
|
104
|
+
|
|
105
|
+
return ExitCodes.USAGE;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
if (
|
|
109
|
+
isFlow
|
|
110
|
+
? values[EventFlags.SUMMARY] !== undefined
|
|
111
|
+
: values[EventFlags.TITLE] !== undefined ||
|
|
112
|
+
values[EventFlags.WHY] !== undefined ||
|
|
113
|
+
values[EventFlags.CONTEXT] !== undefined ||
|
|
114
|
+
values[EventFlags.NEXT] !== undefined
|
|
115
|
+
) {
|
|
116
|
+
process.stderr.write(
|
|
117
|
+
isFlow
|
|
118
|
+
? `event: a flow line takes ${EventFlags.TITLE}, not ${EventFlags.SUMMARY}\n`
|
|
119
|
+
: `event: ${EventFlags.TITLE}, ${EventFlags.WHY}, ${EventFlags.CONTEXT} and ${EventFlags.NEXT} belong to a flow line only\n`,
|
|
120
|
+
);
|
|
99
121
|
|
|
100
122
|
return ExitCodes.USAGE;
|
|
101
123
|
}
|
|
102
124
|
|
|
125
|
+
for (const flag of [EventFlags.CONTEXT, EventFlags.NEXT]) {
|
|
126
|
+
if (values[flag] !== undefined && values[flag].trim() === '') {
|
|
127
|
+
process.stderr.write(`event: ${flag} needs a short text, or leave it out\n`);
|
|
128
|
+
|
|
129
|
+
return ExitCodes.USAGE;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
103
133
|
if (flow !== undefined && !EventFlow.isValid({ flow })) {
|
|
104
134
|
process.stderr.write(`event: ${EventFlags.FLOW} must look like F-12, got '${flow}'\n`);
|
|
105
135
|
|
|
@@ -124,6 +154,12 @@ export class EventCommand {
|
|
|
124
154
|
}
|
|
125
155
|
|
|
126
156
|
const flowId = flow ?? EventFlow.fromBranch({ cwd: opts.cwd });
|
|
157
|
+
|
|
158
|
+
if (isFlow && flowId === undefined) {
|
|
159
|
+
process.stderr.write(`event: a flow line needs ${EventFlags.FLOW} F-n\n`);
|
|
160
|
+
|
|
161
|
+
return ExitCodes.USAGE;
|
|
162
|
+
}
|
|
127
163
|
const actor =
|
|
128
164
|
values[EventFlags.ACTOR] === undefined
|
|
129
165
|
? EventActor.resolve({
|
|
@@ -139,6 +175,9 @@ export class EventCommand {
|
|
|
139
175
|
...(flowId === undefined ? {} : { flowId }),
|
|
140
176
|
...(values[EventFlags.REF] === undefined ? {} : { ref: values[EventFlags.REF] }),
|
|
141
177
|
...(status === undefined ? {} : { status: status as TEventStatus }),
|
|
178
|
+
...(values[EventFlags.WHY] === undefined ? {} : { why: values[EventFlags.WHY] }),
|
|
179
|
+
...(values[EventFlags.CONTEXT] === undefined ? {} : { context: values[EventFlags.CONTEXT] }),
|
|
180
|
+
...(values[EventFlags.NEXT] === undefined ? {} : { next: values[EventFlags.NEXT] }),
|
|
142
181
|
});
|
|
143
182
|
|
|
144
183
|
try {
|
|
@@ -10,6 +10,8 @@ export class EventKinds {
|
|
|
10
10
|
static readonly PR = 'pr';
|
|
11
11
|
/** The owner's answer to a flow, written by whoever relays it; its `status` says which. */
|
|
12
12
|
static readonly DECISION = 'decision';
|
|
13
|
+
/** A flow's title and the one-line reason for it, in the owner's language; the newest per flow wins. */
|
|
14
|
+
static readonly FLOW = 'flow';
|
|
13
15
|
|
|
14
16
|
static readonly SCHEME_SET = new Set<string>([
|
|
15
17
|
this.SESSION_START,
|
|
@@ -21,6 +23,7 @@ export class EventKinds {
|
|
|
21
23
|
this.COMMIT,
|
|
22
24
|
this.PR,
|
|
23
25
|
this.DECISION,
|
|
26
|
+
this.FLOW,
|
|
24
27
|
]);
|
|
25
28
|
|
|
26
29
|
static isValid(value: string): boolean {
|
|
@@ -58,6 +61,10 @@ export class EventFlags {
|
|
|
58
61
|
static readonly FLOW = '--flow';
|
|
59
62
|
static readonly REF = '--ref';
|
|
60
63
|
static readonly STATUS = '--status';
|
|
64
|
+
static readonly TITLE = '--title';
|
|
65
|
+
static readonly WHY = '--why';
|
|
66
|
+
static readonly CONTEXT = '--context';
|
|
67
|
+
static readonly NEXT = '--next';
|
|
61
68
|
static readonly ACTOR = '--actor';
|
|
62
69
|
static readonly DIR = '--dir';
|
|
63
70
|
static readonly SINCE = '--since';
|
|
@@ -101,6 +108,8 @@ export class EventConstants {
|
|
|
101
108
|
static readonly MANIFEST_FILE = '.agents/vulcan.manifest.json';
|
|
102
109
|
static readonly FILE_SUFFIX = '.jsonl';
|
|
103
110
|
static readonly SUMMARY_MAX = 200;
|
|
111
|
+
/** A flow's context is a few sentences, not a summary line. */
|
|
112
|
+
static readonly CONTEXT_MAX = 600;
|
|
104
113
|
/** What a sent message is called when its sender gave no label: the text of a message is never used. */
|
|
105
114
|
static readonly MESSAGE_SENT_LABEL = 'message sent';
|
|
106
115
|
static readonly REF_MAX = 120;
|
|
@@ -16,6 +16,14 @@ export interface IEvent {
|
|
|
16
16
|
/** Only a `decision` has one. */
|
|
17
17
|
status?: TEventStatus;
|
|
18
18
|
ref?: string;
|
|
19
|
+
/** Only a `flow` has one: the one-line reason the flow exists. */
|
|
20
|
+
why?: string;
|
|
21
|
+
/** Only a `flow` has one: what the flow is, what is done and what is left, in a few sentences. */
|
|
22
|
+
context?: string;
|
|
23
|
+
/** Only a `flow` has one: the next step and who does it. */
|
|
24
|
+
next?: string;
|
|
25
|
+
/** Only a `needs-owner` the Claude Code hook wrote has one: the notification type that raised it. */
|
|
26
|
+
notification?: string;
|
|
19
27
|
source: string;
|
|
20
28
|
}
|
|
21
29
|
|
|
@@ -42,6 +50,8 @@ export interface IHookEvent {
|
|
|
42
50
|
kind: TEventKind;
|
|
43
51
|
summary: string;
|
|
44
52
|
ref?: string;
|
|
53
|
+
/** The notification type of a `needs-owner` line. */
|
|
54
|
+
notification?: string;
|
|
45
55
|
/** Text a flow id may be read from: the first line of a message. */
|
|
46
56
|
flowText?: string;
|
|
47
57
|
}
|
package/src/events/hook.ts
CHANGED
|
@@ -55,7 +55,11 @@ export class EventHook {
|
|
|
55
55
|
const type = text({ value: input.notification_type });
|
|
56
56
|
|
|
57
57
|
return ClaudeHookEvents.OWNER_NOTIFICATIONS.has(type)
|
|
58
|
-
? {
|
|
58
|
+
? {
|
|
59
|
+
kind: EventKinds.NEEDS_OWNER,
|
|
60
|
+
summary: text({ value: input.title }) || type,
|
|
61
|
+
notification: type,
|
|
62
|
+
}
|
|
59
63
|
: undefined;
|
|
60
64
|
}
|
|
61
65
|
|
|
@@ -153,6 +157,7 @@ export class EventHook {
|
|
|
153
157
|
source: EventSources.CLAUDE_HOOK,
|
|
154
158
|
...(flowId === undefined ? {} : { flowId }),
|
|
155
159
|
...(mapped.ref === undefined ? {} : { ref: mapped.ref }),
|
|
160
|
+
...(mapped.notification === undefined ? {} : { notification: mapped.notification }),
|
|
156
161
|
...(opts.now === undefined ? {} : { now: opts.now }),
|
|
157
162
|
});
|
|
158
163
|
|
package/src/events/log.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { RecordValue } from '../common/record.ts';
|
|
4
|
-
import { EventConstants, EventKinds, EventStatuses } from './common/index.ts';
|
|
4
|
+
import { ClaudeHookEvents, EventConstants, EventKinds, EventStatuses } from './common/index.ts';
|
|
5
5
|
import type { IEvent, IEventRead, TEventKind, TEventStatus } from './common/index.ts';
|
|
6
6
|
import { EventText } from './text.ts';
|
|
7
7
|
|
|
@@ -39,6 +39,10 @@ export class EventLog {
|
|
|
39
39
|
flowId?: string;
|
|
40
40
|
ref?: string;
|
|
41
41
|
status?: TEventStatus;
|
|
42
|
+
why?: string;
|
|
43
|
+
context?: string;
|
|
44
|
+
next?: string;
|
|
45
|
+
notification?: string;
|
|
42
46
|
now?: number;
|
|
43
47
|
}): IEvent {
|
|
44
48
|
const now = opts.now ?? Date.now();
|
|
@@ -46,6 +50,18 @@ export class EventLog {
|
|
|
46
50
|
opts.ref === undefined
|
|
47
51
|
? ''
|
|
48
52
|
: EventText.oneLine({ text: opts.ref, max: EventConstants.REF_MAX });
|
|
53
|
+
const why =
|
|
54
|
+
opts.why === undefined
|
|
55
|
+
? ''
|
|
56
|
+
: EventText.oneLine({ text: opts.why, max: EventConstants.SUMMARY_MAX });
|
|
57
|
+
const context =
|
|
58
|
+
opts.context === undefined
|
|
59
|
+
? ''
|
|
60
|
+
: EventText.oneLine({ text: opts.context, max: EventConstants.CONTEXT_MAX });
|
|
61
|
+
const next =
|
|
62
|
+
opts.next === undefined
|
|
63
|
+
? ''
|
|
64
|
+
: EventText.oneLine({ text: opts.next, max: EventConstants.SUMMARY_MAX });
|
|
49
65
|
|
|
50
66
|
return {
|
|
51
67
|
id: EventLog.newId({ now }),
|
|
@@ -56,6 +72,13 @@ export class EventLog {
|
|
|
56
72
|
summary: EventText.oneLine({ text: opts.summary, max: EventConstants.SUMMARY_MAX }),
|
|
57
73
|
...(opts.status === undefined ? {} : { status: opts.status }),
|
|
58
74
|
...(ref === '' ? {} : { ref }),
|
|
75
|
+
...(why === '' ? {} : { why }),
|
|
76
|
+
...(context === '' ? {} : { context }),
|
|
77
|
+
...(next === '' ? {} : { next }),
|
|
78
|
+
...(opts.notification !== undefined &&
|
|
79
|
+
ClaudeHookEvents.OWNER_NOTIFICATIONS.has(opts.notification)
|
|
80
|
+
? { notification: opts.notification }
|
|
81
|
+
: {}),
|
|
59
82
|
source: opts.source,
|
|
60
83
|
};
|
|
61
84
|
}
|
|
@@ -130,7 +153,21 @@ export class EventLog {
|
|
|
130
153
|
return undefined;
|
|
131
154
|
}
|
|
132
155
|
|
|
133
|
-
const {
|
|
156
|
+
const {
|
|
157
|
+
id,
|
|
158
|
+
ts,
|
|
159
|
+
flowId,
|
|
160
|
+
actor,
|
|
161
|
+
kind,
|
|
162
|
+
summary,
|
|
163
|
+
status,
|
|
164
|
+
ref,
|
|
165
|
+
why,
|
|
166
|
+
context,
|
|
167
|
+
next,
|
|
168
|
+
notification,
|
|
169
|
+
source,
|
|
170
|
+
} = value;
|
|
134
171
|
|
|
135
172
|
if (
|
|
136
173
|
typeof id !== 'string' ||
|
|
@@ -143,13 +180,20 @@ export class EventLog {
|
|
|
143
180
|
typeof source !== 'string' ||
|
|
144
181
|
(flowId !== undefined && typeof flowId !== 'string') ||
|
|
145
182
|
(status !== undefined && (typeof status !== 'string' || !EventStatuses.isValid(status))) ||
|
|
146
|
-
(ref !== undefined && typeof ref !== 'string')
|
|
183
|
+
(ref !== undefined && typeof ref !== 'string') ||
|
|
184
|
+
(why !== undefined && typeof why !== 'string') ||
|
|
185
|
+
(context !== undefined && typeof context !== 'string') ||
|
|
186
|
+
(next !== undefined && typeof next !== 'string') ||
|
|
187
|
+
(notification !== undefined && typeof notification !== 'string')
|
|
147
188
|
) {
|
|
148
189
|
return undefined;
|
|
149
190
|
}
|
|
150
191
|
|
|
151
192
|
// A reader prints these: whatever a writer put there, no control character reaches a terminal.
|
|
152
193
|
const clean = (field: string): string => EventText.stripControl({ text: field });
|
|
194
|
+
// The free text is cleaned the way `build` cleans it: one line, secrets redacted, the same length cap. A line written by
|
|
195
|
+
// hand, or by an older version, cannot put a huge string or a token on a page.
|
|
196
|
+
const text = (field: string, max: number): string => EventText.oneLine({ text: field, max });
|
|
153
197
|
|
|
154
198
|
return {
|
|
155
199
|
id: clean(id),
|
|
@@ -157,9 +201,16 @@ export class EventLog {
|
|
|
157
201
|
...(flowId === undefined ? {} : { flowId: clean(flowId) }),
|
|
158
202
|
actor: clean(actor),
|
|
159
203
|
kind: kind as TEventKind,
|
|
160
|
-
summary:
|
|
204
|
+
summary: text(summary, EventConstants.SUMMARY_MAX),
|
|
161
205
|
...(status === undefined ? {} : { status: status as TEventStatus }),
|
|
162
|
-
...(ref === undefined ? {} : { ref:
|
|
206
|
+
...(ref === undefined ? {} : { ref: text(ref, EventConstants.REF_MAX) }),
|
|
207
|
+
...(why === undefined ? {} : { why: text(why, EventConstants.SUMMARY_MAX) }),
|
|
208
|
+
...(context === undefined ? {} : { context: text(context, EventConstants.CONTEXT_MAX) }),
|
|
209
|
+
...(next === undefined ? {} : { next: text(next, EventConstants.SUMMARY_MAX) }),
|
|
210
|
+
// A value that is not one of the types the hook knows is dropped: it is a short enum, not free text.
|
|
211
|
+
...(notification === undefined || !ClaudeHookEvents.OWNER_NOTIFICATIONS.has(notification)
|
|
212
|
+
? {}
|
|
213
|
+
: { notification }),
|
|
163
214
|
source: clean(source),
|
|
164
215
|
};
|
|
165
216
|
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a remote host entry may be, for the project config (`remoteHosts.trusted`, `readOnly`) and for the
|
|
3
|
+
* personal list the guard reads at run time. It has no import, because the guard loads no config loader and no zod.
|
|
4
|
+
*/
|
|
5
|
+
export class HostPatterns {
|
|
6
|
+
/** A `$VAR` or `${VAR}`, or a host name made of letters, digits, `.`, `_`, `-` and `*`: never a user, a path or a port. */
|
|
7
|
+
static readonly SHAPE = /^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/;
|
|
8
|
+
|
|
9
|
+
/** A pattern needs a letter or a digit: `*`, `-`, `*-*` or `*_*` would match every host, or every hyphenated one. */
|
|
10
|
+
static hasLiteral(opts: { value: string }): boolean {
|
|
11
|
+
return /[A-Za-z0-9]/.test(opts.value);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
static isValid(opts: { value: string }): boolean {
|
|
15
|
+
return HostPatterns.SHAPE.test(opts.value) && HostPatterns.hasLiteral(opts);
|
|
16
|
+
}
|
|
17
|
+
}
|