@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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.42.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"./worker": "./src/worker.ts",
|
|
16
16
|
"./auth": "./src/lib/auth.ts",
|
|
17
17
|
"./create-admin": "./src/lib/create-admin.ts",
|
|
18
|
+
"./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
|
|
18
19
|
"./package.json": "./package.json"
|
|
19
20
|
},
|
|
20
21
|
"files": [
|
|
@@ -31,6 +32,8 @@
|
|
|
31
32
|
"@openrouter/ai-sdk-provider": "^2.9.1",
|
|
32
33
|
"@scalar/hono-api-reference": "^0.10.19",
|
|
33
34
|
"@t3-oss/env-core": "^0.13.11",
|
|
35
|
+
"@types/papaparse": "^5.5.2",
|
|
36
|
+
"@types/qrcode": "^1.5.6",
|
|
34
37
|
"acorn": "^8.17.0",
|
|
35
38
|
"acorn-walk": "^8.3.5",
|
|
36
39
|
"ai": "^6.0.209",
|
|
@@ -46,19 +49,17 @@
|
|
|
46
49
|
"svix": "^1.95.1",
|
|
47
50
|
"winston": "^3.19.0",
|
|
48
51
|
"zod": "^4.4.3",
|
|
49
|
-
"@hogsend/core": "^0.
|
|
50
|
-
"@hogsend/db": "^0.
|
|
51
|
-
"@hogsend/email": "^0.
|
|
52
|
-
"@hogsend/plugin-posthog": "^0.
|
|
53
|
-
"@hogsend/plugin-resend": "^0.
|
|
52
|
+
"@hogsend/core": "^0.42.0",
|
|
53
|
+
"@hogsend/db": "^0.42.0",
|
|
54
|
+
"@hogsend/email": "^0.42.0",
|
|
55
|
+
"@hogsend/plugin-posthog": "^0.42.0",
|
|
56
|
+
"@hogsend/plugin-resend": "^0.42.0"
|
|
54
57
|
},
|
|
55
58
|
"optionalDependencies": {
|
|
56
|
-
"@hogsend/plugin-postmark": "^0.
|
|
59
|
+
"@hogsend/plugin-postmark": "^0.42.0"
|
|
57
60
|
},
|
|
58
61
|
"devDependencies": {
|
|
59
62
|
"@types/node": "^22.15.3",
|
|
60
|
-
"@types/papaparse": "^5.5.2",
|
|
61
|
-
"@types/qrcode": "^1.5.6",
|
|
62
63
|
"tsx": "^4.22.3",
|
|
63
64
|
"@repo/typescript-config": "0.0.0"
|
|
64
65
|
},
|
package/src/index.ts
CHANGED
|
@@ -307,6 +307,8 @@ export {
|
|
|
307
307
|
type EnableBlueprintResult,
|
|
308
308
|
enableBlueprint,
|
|
309
309
|
findBlueprintRow,
|
|
310
|
+
type PromoteBlueprintResult,
|
|
311
|
+
promoteBlueprint,
|
|
310
312
|
type SerializedBlueprint,
|
|
311
313
|
serializeBlueprint,
|
|
312
314
|
type UpdateBlueprintPatch,
|
|
@@ -615,6 +617,12 @@ export {
|
|
|
615
617
|
resetListRegistry,
|
|
616
618
|
setListRegistry,
|
|
617
619
|
} from "./lists/registry-singleton.js";
|
|
620
|
+
// --- Journey blueprints: shared authoring-guide text (tools + @hogsend/mcp) ---
|
|
621
|
+
export {
|
|
622
|
+
BLUEPRINT_AUTHORING_GUIDE,
|
|
623
|
+
GRAPH_FORMAT,
|
|
624
|
+
ISSUE_LOOP_HINT,
|
|
625
|
+
} from "./mcp/authoring-guide.js";
|
|
618
626
|
// --- Journey blueprints: agent-facing authoring tools (spec §9, phase 4) ---
|
|
619
627
|
export {
|
|
620
628
|
type BlueprintToolDefinition,
|
|
@@ -624,6 +632,12 @@ export {
|
|
|
624
632
|
type JourneyBlueprintTools,
|
|
625
633
|
type JourneyBlueprintToolsOptions,
|
|
626
634
|
} from "./mcp/blueprint-tools.js";
|
|
635
|
+
export {
|
|
636
|
+
createRateLimit,
|
|
637
|
+
type RateLimitOptions,
|
|
638
|
+
} from "./middleware/rate-limit.js";
|
|
639
|
+
// --- Middleware (consumer-mounted routes, e.g. the @hogsend/mcp hosted route) ---
|
|
640
|
+
export { requireAdmin } from "./middleware/require-admin.js";
|
|
627
641
|
// --- Webhook sources ---
|
|
628
642
|
export {
|
|
629
643
|
type DefinedWebhookSource,
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
} from "@hogsend/db";
|
|
19
19
|
import { and, eq, inArray, notInArray, sql } from "drizzle-orm";
|
|
20
20
|
import { getAnalytics } from "../lib/analytics-singleton.js";
|
|
21
|
+
import { blueprintGraphLock } from "../lib/blueprint-lock.js";
|
|
21
22
|
import { getDb } from "../lib/db.js";
|
|
22
23
|
import {
|
|
23
24
|
checkEmailPreferences,
|
|
@@ -122,24 +123,48 @@ export async function insertEnrollment(opts: {
|
|
|
122
123
|
journeyId: string;
|
|
123
124
|
context: Record<string, unknown>;
|
|
124
125
|
hatchetRunId?: string;
|
|
126
|
+
/**
|
|
127
|
+
* Blueprint runs serialize this insert against a concurrent GRAPH EDIT via a
|
|
128
|
+
* transaction-scoped advisory lock — `updateBlueprint` takes the SAME lock
|
|
129
|
+
* ({@link blueprintGraphLock}) around its in-flight count + guarded update,
|
|
130
|
+
* so an enrollment cannot become active/waiting in the window between that
|
|
131
|
+
* count and update. Code journeys have no mutable graph, so they insert
|
|
132
|
+
* lock-free (the default).
|
|
133
|
+
*/
|
|
134
|
+
serializeWithGraphLock?: boolean;
|
|
125
135
|
}): Promise<JourneyStateRow | undefined> {
|
|
126
|
-
const
|
|
127
|
-
.
|
|
128
|
-
.
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
.
|
|
142
|
-
|
|
136
|
+
const values = {
|
|
137
|
+
userId: opts.userId,
|
|
138
|
+
userEmail: opts.userEmail,
|
|
139
|
+
journeyId: opts.journeyId,
|
|
140
|
+
currentNodeId: "start",
|
|
141
|
+
status: "active" as const,
|
|
142
|
+
context: opts.context,
|
|
143
|
+
hatchetRunId: opts.hatchetRunId,
|
|
144
|
+
};
|
|
145
|
+
const onConflict = {
|
|
146
|
+
target: [journeyStates.userId, journeyStates.journeyId],
|
|
147
|
+
where: sql`status IN ('active', 'waiting')`,
|
|
148
|
+
};
|
|
149
|
+
|
|
150
|
+
if (!opts.serializeWithGraphLock) {
|
|
151
|
+
const [row] = await opts.db
|
|
152
|
+
.insert(journeyStates)
|
|
153
|
+
.values(values)
|
|
154
|
+
.onConflictDoNothing(onConflict)
|
|
155
|
+
.returning();
|
|
156
|
+
return row;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
return opts.db.transaction(async (tx) => {
|
|
160
|
+
await tx.execute(blueprintGraphLock(opts.journeyId));
|
|
161
|
+
const [row] = await tx
|
|
162
|
+
.insert(journeyStates)
|
|
163
|
+
.values(values)
|
|
164
|
+
.onConflictDoNothing(onConflict)
|
|
165
|
+
.returning();
|
|
166
|
+
return row;
|
|
167
|
+
});
|
|
143
168
|
}
|
|
144
169
|
|
|
145
170
|
export interface ExecuteJourneyRunOptions {
|
|
@@ -162,6 +187,13 @@ export interface ExecuteJourneyRunOptions {
|
|
|
162
187
|
* interpreter pins `__blueprintVersion` here (spec §12).
|
|
163
188
|
*/
|
|
164
189
|
extraContext?: Record<string, unknown>;
|
|
190
|
+
/**
|
|
191
|
+
* Serialize the enrollment insert against a concurrent blueprint graph edit
|
|
192
|
+
* with a transaction-scoped advisory lock (spec §12). Set by the blueprint
|
|
193
|
+
* interpreter — the blueprint id IS the journeyId, so the lock key matches
|
|
194
|
+
* `updateBlueprint`'s. Code journeys leave it unset (no mutable graph).
|
|
195
|
+
*/
|
|
196
|
+
serializeEnrollment?: boolean;
|
|
165
197
|
/**
|
|
166
198
|
* Serialize a run failure into `journeyStates.errorMessage`. Defaults to the
|
|
167
199
|
* error's message; the blueprint interpreter writes the structured
|
|
@@ -295,6 +327,7 @@ export async function executeJourneyRun(
|
|
|
295
327
|
? { ...properties, ...options.extraContext }
|
|
296
328
|
: properties,
|
|
297
329
|
hatchetRunId: workflowRunId,
|
|
330
|
+
serializeWithGraphLock: options.serializeEnrollment,
|
|
298
331
|
});
|
|
299
332
|
if (!state) {
|
|
300
333
|
return { status: "skipped", reason: "already_active" };
|
|
@@ -1089,6 +1089,38 @@ export function createJourneyContext(
|
|
|
1089
1089
|
});
|
|
1090
1090
|
},
|
|
1091
1091
|
|
|
1092
|
+
async exit(reason?: string): Promise<never> {
|
|
1093
|
+
// Terminal "exited": a guarded flip (never clobber an already-terminal
|
|
1094
|
+
// row) plus the SAME JourneyExitedError control-flow signal a mid-wait
|
|
1095
|
+
// exitOn raises — the run lifecycle maps it to { status: "exited" } with
|
|
1096
|
+
// no "failed"/"completed" write and no journey:* event. This is the
|
|
1097
|
+
// single mechanism the blueprint interpreter's end-exited node drives too
|
|
1098
|
+
// (and the form promote-to-code emits), so there is one path, not two.
|
|
1099
|
+
const now = new Date();
|
|
1100
|
+
const [exited] = await db
|
|
1101
|
+
.update(journeyStates)
|
|
1102
|
+
.set({ status: "exited", exitedAt: now, updatedAt: now })
|
|
1103
|
+
.where(
|
|
1104
|
+
and(
|
|
1105
|
+
eq(journeyStates.id, stateId),
|
|
1106
|
+
notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
|
|
1107
|
+
),
|
|
1108
|
+
)
|
|
1109
|
+
.returning({ id: journeyStates.id });
|
|
1110
|
+
if (exited) {
|
|
1111
|
+
// Fire-and-forget exit transition (best-effort; never affects the run).
|
|
1112
|
+
logTransition({
|
|
1113
|
+
db,
|
|
1114
|
+
journeyStateId: stateId,
|
|
1115
|
+
from: getJourneyBoundary()?.currentLabel ?? null,
|
|
1116
|
+
to: "end-exited",
|
|
1117
|
+
action: "exited",
|
|
1118
|
+
...(reason ? { detail: { reason } } : {}),
|
|
1119
|
+
});
|
|
1120
|
+
}
|
|
1121
|
+
throw new JourneyExitedError(stateId);
|
|
1122
|
+
},
|
|
1123
|
+
|
|
1092
1124
|
async now() {
|
|
1093
1125
|
return refreshNow();
|
|
1094
1126
|
},
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { type SQL, sql } from "drizzle-orm";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Transaction-scoped advisory lock serializing a blueprint's graph EDIT
|
|
5
|
+
* (`updateBlueprint`'s in-flight count + guarded update) against a new
|
|
6
|
+
* ENROLLMENT insert for the same blueprint (`insertEnrollment` for a blueprint
|
|
7
|
+
* run). Both sides take THIS lock inside their transaction, so the count and
|
|
8
|
+
* the insert cannot interleave: an enrollment either lands before the count
|
|
9
|
+
* (the edit then sees it and rejects with `in_flight`) or after the graph
|
|
10
|
+
* commits (a fresh run walking the NEW graph) — never mid-flight, which is the
|
|
11
|
+
* interleaving that would desync the positional Hatchet replay journal for a
|
|
12
|
+
* run suspended between the count and the update.
|
|
13
|
+
*
|
|
14
|
+
* `hashtext` folds the id into the int4 the single-arg `pg_advisory_xact_lock`
|
|
15
|
+
* overload casts to bigint (same pattern as `contacts.ts`/`boot-api-key.ts`);
|
|
16
|
+
* the `bp-graph:` prefix namespaces it away from the codebase's other advisory
|
|
17
|
+
* locks. Xact-scoped — released on commit/rollback, no manual unlock.
|
|
18
|
+
*/
|
|
19
|
+
export function blueprintGraphLock(blueprintId: string): SQL {
|
|
20
|
+
return sql`SELECT pg_advisory_xact_lock(hashtext(${`bp-graph:${blueprintId}`}))`;
|
|
21
|
+
}
|