@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.9",
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.9",
48
- "@venizia/vulcan-okf": "0.4.9",
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
- const events = BoardFold.prepare({ lines });
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
- flows.push(BoardFold.flowOf({ id, events, owner: opts.owner }));
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 to = line.ref?.startsWith(TO_PREFIX) ? line.ref.slice(TO_PREFIX.length) : undefined;
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 { ...base, kind: BoardKinds.MSG, stage: -1, ...(to === undefined ? {} : { to }) };
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
- return { ...base, kind: BoardKinds.NOTE, stage: -1, needsOwner: true };
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
@@ -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
- /^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/,
203
- 'a host name or a pattern with *, not a user, a path or a port',
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 trusted hosts, one per line.
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
  }),
@@ -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 summary = values[EventFlags.SUMMARY];
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(`event: ${EventFlags.SUMMARY} needs a short text\n`);
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
  }
@@ -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
- ? { kind: EventKinds.NEEDS_OWNER, summary: text({ value: input.title }) || type }
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 { id, ts, flowId, actor, kind, summary, status, ref, source } = value;
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: clean(summary),
204
+ summary: text(summary, EventConstants.SUMMARY_MAX),
161
205
  ...(status === undefined ? {} : { status: status as TEventStatus }),
162
- ...(ref === undefined ? {} : { ref: clean(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
+ }