@hogsend/engine 0.41.0 → 0.42.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/package.json +10 -9
- package/src/index.ts +14 -0
- package/src/journeys/execute-journey-run.ts +50 -17
- package/src/journeys/journey-context.ts +32 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +273 -46
- package/src/lib/event-names.ts +143 -0
- package/src/lib/tracking.ts +1 -5
- package/src/mcp/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +38 -108
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +94 -10
- package/src/routes/admin/events.ts +55 -0
- package/src/workflows/journey-blueprint-interpreter.ts +128 -33
|
@@ -2,6 +2,10 @@ import { contacts, userEvents } from "@hogsend/db";
|
|
|
2
2
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
3
|
import { and, count, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
|
|
4
4
|
import type { AppEnv } from "../../app.js";
|
|
5
|
+
import {
|
|
6
|
+
eventNameEntrySchema,
|
|
7
|
+
listEventNameVocabulary,
|
|
8
|
+
} from "../../lib/event-names.js";
|
|
5
9
|
import { ingestEvent } from "../../lib/ingestion.js";
|
|
6
10
|
|
|
7
11
|
const eventSchema = z.object({
|
|
@@ -114,6 +118,41 @@ const getRoute = createRoute({
|
|
|
114
118
|
},
|
|
115
119
|
});
|
|
116
120
|
|
|
121
|
+
const namesRoute = createRoute({
|
|
122
|
+
method: "get",
|
|
123
|
+
path: "/names",
|
|
124
|
+
tags: ["Admin — Events"],
|
|
125
|
+
summary: "List event names (observed + declared)",
|
|
126
|
+
description:
|
|
127
|
+
"Best-effort event-name vocabulary for authoring triggers, waits, and " +
|
|
128
|
+
"exitOn rules. Event names are an OPEN vocabulary (no closed registry " +
|
|
129
|
+
"exists anywhere in the engine), so this merges: events actually " +
|
|
130
|
+
"observed in the event store (with occurrence counts, most recently " +
|
|
131
|
+
"seen first) and events referenced as code-journey or blueprint " +
|
|
132
|
+
"triggers. Any other event name is also valid — it just hasn't been " +
|
|
133
|
+
"seen yet.",
|
|
134
|
+
request: {
|
|
135
|
+
query: z.object({
|
|
136
|
+
// Case-insensitive substring filter on the event name.
|
|
137
|
+
search: z.string().min(1).optional(),
|
|
138
|
+
limit: z.coerce.number().int().min(1).max(200).default(100),
|
|
139
|
+
}),
|
|
140
|
+
},
|
|
141
|
+
responses: {
|
|
142
|
+
200: {
|
|
143
|
+
content: {
|
|
144
|
+
"application/json": {
|
|
145
|
+
schema: z.object({
|
|
146
|
+
note: z.string(),
|
|
147
|
+
events: z.array(eventNameEntrySchema),
|
|
148
|
+
}),
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
description: "Merged observed + declared event-name vocabulary",
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
|
|
117
156
|
const exitSchema = z.object({
|
|
118
157
|
journeyId: z.string(),
|
|
119
158
|
stateId: z.string(),
|
|
@@ -217,6 +256,22 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
|
|
|
217
256
|
200,
|
|
218
257
|
);
|
|
219
258
|
})
|
|
259
|
+
// Registered before getRoute so the literal "names" is never captured as
|
|
260
|
+
// an {id}. Delegates to the shared vocabulary helper (lib/event-names.ts)
|
|
261
|
+
// — the same implementation the blueprint tools' `list_events` serves, so
|
|
262
|
+
// the HTTP surface and the in-process tool can never drift.
|
|
263
|
+
.openapi(namesRoute, async (c) => {
|
|
264
|
+
const { db, registry } = c.get("container");
|
|
265
|
+
const { search, limit } = c.req.valid("query");
|
|
266
|
+
|
|
267
|
+
const { note, events } = await listEventNameVocabulary({
|
|
268
|
+
db,
|
|
269
|
+
registry,
|
|
270
|
+
search,
|
|
271
|
+
limit,
|
|
272
|
+
});
|
|
273
|
+
return c.json({ note, events }, 200);
|
|
274
|
+
})
|
|
220
275
|
.openapi(getRoute, async (c) => {
|
|
221
276
|
const { db } = c.get("container");
|
|
222
277
|
const { id } = c.req.valid("param");
|
|
@@ -5,9 +5,11 @@ import {
|
|
|
5
5
|
BlueprintUnreachableNodeError,
|
|
6
6
|
type DurationObject,
|
|
7
7
|
evaluateCondition,
|
|
8
|
+
isReservedEventName,
|
|
8
9
|
type JourneyEdge,
|
|
9
10
|
type JourneyNode,
|
|
10
11
|
type PropertyCondition,
|
|
12
|
+
RESERVED_EVENT_NAMESPACES,
|
|
11
13
|
serializeBlueprintError,
|
|
12
14
|
validateBlueprintGraph,
|
|
13
15
|
} from "@hogsend/core";
|
|
@@ -310,6 +312,17 @@ export async function walkBlueprintGraph(
|
|
|
310
312
|
"event",
|
|
311
313
|
node.meta?.event,
|
|
312
314
|
);
|
|
315
|
+
// Save-time validation rejects reserved namespaces since the check
|
|
316
|
+
// was added, but the graph column is jsonb — a row saved BEFORE the
|
|
317
|
+
// rule (or written out-of-band) must still never forge an
|
|
318
|
+
// engine-emitted event through the ingest pipeline.
|
|
319
|
+
if (isReservedEventName(event)) {
|
|
320
|
+
throw new BlueprintNodeExecutionError(
|
|
321
|
+
blueprintId,
|
|
322
|
+
node.id,
|
|
323
|
+
`trigger node event "${event}" uses a reserved namespace (${RESERVED_EVENT_NAMESPACES.join("/")})`,
|
|
324
|
+
);
|
|
325
|
+
}
|
|
313
326
|
await ctx.trigger({
|
|
314
327
|
event,
|
|
315
328
|
userId: user.id,
|
|
@@ -358,37 +371,12 @@ export async function walkBlueprintGraph(
|
|
|
358
371
|
// code journey's run() returning normally.
|
|
359
372
|
return null;
|
|
360
373
|
|
|
361
|
-
case "end-exited":
|
|
362
|
-
// Terminal:
|
|
363
|
-
//
|
|
364
|
-
//
|
|
365
|
-
// a "failed" write or a journey:failed push.
|
|
366
|
-
|
|
367
|
-
const [exited] = await db
|
|
368
|
-
.update(journeyStates)
|
|
369
|
-
.set({
|
|
370
|
-
status: "exited",
|
|
371
|
-
exitedAt: new Date(),
|
|
372
|
-
updatedAt: new Date(),
|
|
373
|
-
})
|
|
374
|
-
.where(
|
|
375
|
-
and(
|
|
376
|
-
eq(journeyStates.id, user.stateId),
|
|
377
|
-
notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
|
|
378
|
-
),
|
|
379
|
-
)
|
|
380
|
-
.returning({ id: journeyStates.id });
|
|
381
|
-
if (exited) {
|
|
382
|
-
logTransition({
|
|
383
|
-
db,
|
|
384
|
-
journeyStateId: user.stateId,
|
|
385
|
-
from: null,
|
|
386
|
-
to: "end-exited",
|
|
387
|
-
action: "exited",
|
|
388
|
-
});
|
|
389
|
-
}
|
|
390
|
-
throw new JourneyExitedError(user.stateId);
|
|
391
|
-
}
|
|
374
|
+
case "end-exited":
|
|
375
|
+
// Terminal "exited": the SAME primitive a code journey (and promoted
|
|
376
|
+
// blueprint code) calls — a guarded flip to "exited" plus the
|
|
377
|
+
// JourneyExitedError the lifecycle maps to { status: "exited" } without
|
|
378
|
+
// a "failed" write or a journey:failed push. One mechanism, not two.
|
|
379
|
+
return ctx.exit();
|
|
392
380
|
|
|
393
381
|
case "end-failed":
|
|
394
382
|
// Terminal: matches a code journey's thrown error — the lifecycle
|
|
@@ -459,6 +447,75 @@ export async function walkBlueprintGraph(
|
|
|
459
447
|
}
|
|
460
448
|
}
|
|
461
449
|
|
|
450
|
+
/**
|
|
451
|
+
* A REPLAY (resume recovered by run id) that can no longer execute — the
|
|
452
|
+
* blueprint row vanished, or its stored graph now fails execution-time
|
|
453
|
+
* re-validation — must FAIL the recovered enrollment, not return `skipped`
|
|
454
|
+
* and leave a waiting/active row stranded non-terminal forever. Recovery is by
|
|
455
|
+
* the replay-stable Hatchet run id + journeyId, exactly as `executeJourneyRun`
|
|
456
|
+
* recovers an enrollment; a FRESH (never-enrolled) dispatch recovers nothing
|
|
457
|
+
* and the caller keeps returning `skipped` unchanged.
|
|
458
|
+
*
|
|
459
|
+
* Mirrors the failed path in `executeJourneyRun`: a guarded flip to "failed"
|
|
460
|
+
* (`notInArray(TERMINAL_STATUSES)`, so an already-terminal row is never
|
|
461
|
+
* clobbered) plus the same `journey:failed` side effects (structured
|
|
462
|
+
* errorMessage, failed transition, event push). Returns whether an existing
|
|
463
|
+
* enrollment was recovered for this run.
|
|
464
|
+
*/
|
|
465
|
+
async function failRecoveredBlueprintEnrollment(opts: {
|
|
466
|
+
db: Database;
|
|
467
|
+
blueprintId: string;
|
|
468
|
+
workflowRunId: string;
|
|
469
|
+
userId: string;
|
|
470
|
+
message: string;
|
|
471
|
+
}): Promise<boolean> {
|
|
472
|
+
const { db, blueprintId, workflowRunId, userId, message } = opts;
|
|
473
|
+
if (!workflowRunId) return false;
|
|
474
|
+
|
|
475
|
+
const recovered = await db.query.journeyStates.findFirst({
|
|
476
|
+
where: and(
|
|
477
|
+
eq(journeyStates.hatchetRunId, workflowRunId),
|
|
478
|
+
eq(journeyStates.journeyId, blueprintId),
|
|
479
|
+
),
|
|
480
|
+
});
|
|
481
|
+
if (!recovered) return false;
|
|
482
|
+
|
|
483
|
+
const [failed] = await db
|
|
484
|
+
.update(journeyStates)
|
|
485
|
+
.set({ status: "failed", errorMessage: message, updatedAt: new Date() })
|
|
486
|
+
.where(
|
|
487
|
+
and(
|
|
488
|
+
eq(journeyStates.id, recovered.id),
|
|
489
|
+
notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
|
|
490
|
+
),
|
|
491
|
+
)
|
|
492
|
+
.returning({ id: journeyStates.id });
|
|
493
|
+
// Already terminal — nothing was stranded; the recovery still happened.
|
|
494
|
+
if (!failed) return true;
|
|
495
|
+
|
|
496
|
+
logger.error("blueprint replay failed the recovered enrollment", {
|
|
497
|
+
blueprintId,
|
|
498
|
+
stateId: recovered.id,
|
|
499
|
+
userId,
|
|
500
|
+
error: message,
|
|
501
|
+
});
|
|
502
|
+
logTransition({
|
|
503
|
+
db,
|
|
504
|
+
journeyStateId: recovered.id,
|
|
505
|
+
from: recovered.currentNodeId ?? null,
|
|
506
|
+
to: null,
|
|
507
|
+
action: "failed",
|
|
508
|
+
detail: { error: message },
|
|
509
|
+
});
|
|
510
|
+
await hatchet.events.push("journey:failed", {
|
|
511
|
+
journeyId: blueprintId,
|
|
512
|
+
stateId: recovered.id,
|
|
513
|
+
userId,
|
|
514
|
+
error: message,
|
|
515
|
+
});
|
|
516
|
+
return true;
|
|
517
|
+
}
|
|
518
|
+
|
|
462
519
|
/**
|
|
463
520
|
* The event payload `checkBlueprintTriggers` pushes for each matching enabled
|
|
464
521
|
* blueprint — one push per (blueprint, user) enrollment attempt.
|
|
@@ -498,6 +555,11 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
|
|
|
498
555
|
fn: async (input: BlueprintRunPayload, hatchetCtx) => {
|
|
499
556
|
const db = getDb();
|
|
500
557
|
const blueprintId = input.blueprintId as string;
|
|
558
|
+
// Recovery anchor: a REPLAY resumes under the SAME run id, so a blueprint
|
|
559
|
+
// that has since vanished / gone invalid must fail its recovered
|
|
560
|
+
// enrollment rather than strand it (see failRecoveredBlueprintEnrollment).
|
|
561
|
+
const workflowRunId = hatchetCtx.workflowRunId();
|
|
562
|
+
const userId = input.userId as string;
|
|
501
563
|
|
|
502
564
|
const row = await db.query.journeyBlueprints.findFirst({
|
|
503
565
|
where: eq(journeyBlueprints.id, blueprintId),
|
|
@@ -506,7 +568,21 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
|
|
|
506
568
|
logger.warn("blueprint run skipped: blueprint not found", {
|
|
507
569
|
blueprintId,
|
|
508
570
|
});
|
|
509
|
-
|
|
571
|
+
const failed = await failRecoveredBlueprintEnrollment({
|
|
572
|
+
db,
|
|
573
|
+
blueprintId,
|
|
574
|
+
workflowRunId,
|
|
575
|
+
userId,
|
|
576
|
+
message: JSON.stringify(
|
|
577
|
+
serializeBlueprintError(
|
|
578
|
+
blueprintId,
|
|
579
|
+
new Error("blueprint row not found at execution time"),
|
|
580
|
+
),
|
|
581
|
+
),
|
|
582
|
+
});
|
|
583
|
+
return failed
|
|
584
|
+
? { status: "failed", reason: "blueprint_not_found" }
|
|
585
|
+
: { status: "skipped", reason: "blueprint_not_found" };
|
|
510
586
|
}
|
|
511
587
|
|
|
512
588
|
// Defense-in-depth (spec §6): a saved blueprint already passed
|
|
@@ -518,7 +594,21 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
|
|
|
518
594
|
"blueprint run skipped: stored graph failed execution-time validation",
|
|
519
595
|
{ blueprintId, issues: validated.issues },
|
|
520
596
|
);
|
|
521
|
-
|
|
597
|
+
const failed = await failRecoveredBlueprintEnrollment({
|
|
598
|
+
db,
|
|
599
|
+
blueprintId,
|
|
600
|
+
workflowRunId,
|
|
601
|
+
userId,
|
|
602
|
+
message: JSON.stringify(
|
|
603
|
+
serializeBlueprintError(
|
|
604
|
+
blueprintId,
|
|
605
|
+
new Error("stored graph failed execution-time re-validation"),
|
|
606
|
+
),
|
|
607
|
+
),
|
|
608
|
+
});
|
|
609
|
+
return failed
|
|
610
|
+
? { status: "failed", reason: "invalid_blueprint_graph" }
|
|
611
|
+
: { status: "skipped", reason: "invalid_blueprint_graph" };
|
|
522
612
|
}
|
|
523
613
|
|
|
524
614
|
// Version pin (spec §12): the version this run enrolled under, recorded
|
|
@@ -551,6 +641,11 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
|
|
|
551
641
|
} satisfies EventPayloadInput,
|
|
552
642
|
hatchetCtx,
|
|
553
643
|
extraContext: { __blueprintVersion: enrolledVersion },
|
|
644
|
+
// Serialize this enrollment insert against a concurrent graph edit
|
|
645
|
+
// (updateBlueprint takes the SAME advisory lock around its in-flight
|
|
646
|
+
// count + update) so the run cannot become active between that count and
|
|
647
|
+
// the graph write — the desync window the in-flight gate exists to close.
|
|
648
|
+
serializeEnrollment: true,
|
|
554
649
|
// Structured errorMessage (spec §6.1): { blueprintId, nodeId, message }
|
|
555
650
|
// as JSON in the SAME journeyStates.errorMessage field code journeys
|
|
556
651
|
// use, so Studio's error display needs no blueprint-specific branching.
|