@voltro/plugin-ai-flows 0.84.0 → 0.86.0

package/dist/procedures.js

@@ -0,0 +1,208 @@
+import { aiFlowRunsTable as e, aiFlowsTable as t } from "./table.js";
+import { FLOW_RUN_WORKFLOW as n, flowRunWorkflow as r, humanResponseSignalName as i } from "./workflow.js";
+import { FlowCancelReceipt as a, FlowReviewInput as o, FlowReviewReceipt as s, FlowStartReceipt as c } from "./ir.js";
+import { FlowBriefIncomplete as l, FlowNotAwaitingResponse as u, FlowReviewDeliveryError as d, FlowRunNotFound as f } from "./errors.js";
+import { resolveIr as p } from "./engine.js";
+import { recordFlowStartReceipt as m } from "./startReceipt.js";
+import { Effect as h, Result as g, Schema as _ } from "effect";
+import { WorkflowControlResultSchema as v } from "@voltro/protocol";
+import { and as y, eq as b, inSet as x, queryFor as S } from "@voltro/database";
+//#region src/procedures.ts
+var C = () => globalThis.crypto?.randomUUID?.() ?? `req-${Date.now().toString(36)}`, w = (e) => e.request?.subject?.id ?? null, T = (t, n) => h.promise(() => t.store.query(S(e).where(b("id", n)).descriptor)).pipe(h.map((e) => e[0])), E = (e) => h.sync(() => {
+	let t = e.workflows;
+	if (!t) throw Error("workflow runtime unavailable; no flow start was submitted");
+	return t;
+}), D = (t, r) => h.gen(function* () {
+	yield* E(t);
+	let i = yield* p(t, r.flowRef), a = r.input ?? {}, o = i.brief.filter((e) => e.required && e.type !== "boolean" && (a[e.key] === void 0 || a[e.key] === null || a[e.key] === "")).map((e) => e.key);
+	if (o.length > 0) return yield* h.fail(new l({
+		missing: o,
+		message: `missing required brief field(s): ${o.join(", ")}`
+	}));
+	let s = C(), u = `run-${s}`, d = r.source ?? "manual";
+	return yield* h.promise(() => t.transaction(async (t) => {
+		let o = t.workflows;
+		if (!o) throw Error("workflow runtime unavailable in transaction; no flow start was submitted");
+		await t.store.insert(e.tableName, {
+			id: u,
+			flowRef: r.flowRef,
+			flowName: i.name,
+			mode: i.mode,
+			status: "pending",
+			source: d,
+			requestId: s,
+			input: a,
+			ownerId: w(t)
+		});
+		let l = await m(t, u, await o.start(n, {
+			runId: u,
+			flowRef: r.flowRef,
+			input: a,
+			source: d,
+			requestId: s
+		}));
+		return c.make({
+			runId: u,
+			requestId: s,
+			admission: l
+		});
+	}));
+}), O = (t, i) => h.gen(function* () {
+	return yield* E(t), yield* h.tryPromise({
+		try: () => t.transaction(async (t) => {
+			let a = t.workflows;
+			if (!a) throw Error("workflow runtime unavailable in transaction; no flow start was submitted");
+			let o = (await t.store.query(S(e).where(b("id", i.runId)).descriptor))[0];
+			if (!o) throw new f({
+				runId: i.runId,
+				message: "run not found"
+			});
+			let s = o.requestId;
+			if (typeof s != "string" || s.length === 0) throw Error("stored flow run has no valid requestId; retry refused without changing the run");
+			let l = _.decodeUnknownResult(r.payloadSchema.pipe(_.check(_.makeFilter((e) => e.runId === i.runId && e.flowRef.length > 0))))({
+				...o,
+				runId: o.id
+			});
+			if (g.isFailure(l)) throw Error("stored workflow payload is incomplete or invalid; retry refused without changing the run");
+			let u = await m(t, i.runId, await a.start(n, l.success));
+			return c.make({
+				runId: i.runId,
+				requestId: s,
+				admission: u
+			});
+		}),
+		catch: (e) => e
+	}).pipe(h.catch((e) => e instanceof f ? h.fail(e) : h.die(e)));
+}), k = (t, i) => h.gen(function* () {
+	let o = yield* T(t, i.runId);
+	if (!o) return yield* h.fail(new f({
+		runId: i.runId,
+		message: "run not found"
+	}));
+	if (A(o.status)) return a.make({
+		runId: i.runId,
+		status: o.status,
+		engine: "not-requested",
+		control: null
+	});
+	let s = (/* @__PURE__ */ new Date()).toISOString();
+	yield* h.promise(() => t.store.updateMany(e.tableName, {
+		status: "cancelling",
+		cancelledAt: s
+	}, { where: y(b("id", i.runId), x("status", [
+		"pending",
+		"running",
+		"waiting"
+	])) }));
+	let c = yield* T(t, i.runId);
+	if (!c) return yield* h.fail(new f({
+		runId: i.runId,
+		message: "run not found"
+	}));
+	if (A(c.status)) return a.make({
+		runId: i.runId,
+		status: c.status,
+		engine: "not-requested",
+		control: null
+	});
+	let l = t.workflows, u = _.decodeUnknownOption(_.Struct({
+		runId: _.Literal(i.runId),
+		flowRef: _.NonEmptyString,
+		requestId: _.NonEmptyString,
+		input: _.Record(_.String, _.Unknown),
+		source: _.Literals(["manual", "cron"])
+	}))({
+		...o,
+		runId: o.id
+	}), d = l === void 0 || u._tag === "None" ? null : yield* h.flatMap(r.executionId(u.value), (e) => h.tryPromise(async () => {
+		let t = _.decodeUnknownSync(v)(await l.cancel(n, e));
+		if (t.operation !== "cancel" || t.snapshot.workflowName !== "flow.run" || t.snapshot.executionId !== e) throw Error("workflow cancellation receipt does not match the flow execution");
+		return t;
+	})).pipe(h.catch(() => h.succeed(null))), p = d === null ? l === void 0 || u._tag === "None" ? "unreachable" : "unknown" : d.snapshot.status === "cancelled" && (d.kind === "confirmed" || d.kind === "already-terminal") ? "cancelled" : d.kind === "accepted" ? "accepted" : d.kind === "already-terminal" ? "already-terminal" : "unknown", m = y(b("id", i.runId), b("status", "cancelling"), b("cancelledAt", c.cancelledAt));
+	if (p === "cancelled") yield* h.promise(() => t.store.updateMany(e.tableName, {
+		status: "cancelled",
+		completedAt: c.completedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+	}, { where: m }));
+	else if (d?.kind === "already-terminal") {
+		let n = _.decodeUnknownOption(r.successSchema)(d.snapshot.output), a = d.snapshot.status === "failed" ? "failed" : n._tag === "Some" && n.value.runId === i.runId && n.value.status !== "waiting" ? n.value.status : void 0;
+		a !== void 0 && (yield* h.promise(() => t.store.updateMany(e.tableName, {
+			status: a,
+			completedAt: c.completedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+			...a === "cancelled" ? {} : { cancelledAt: null }
+		}, { where: m })));
+	}
+	let g = yield* T(t, i.runId);
+	return g ? yield* _.decodeUnknownEffect(a)({
+		runId: i.runId,
+		status: g.status,
+		engine: p,
+		control: d
+	}).pipe(h.orDie) : yield* h.fail(new f({
+		runId: i.runId,
+		message: "run not found"
+	}));
+}), A = (e) => e === "succeeded" || e === "failed" || e === "cancelled", j = (e) => {
+	let t = e.steps?.filter((e) => e.status === "waiting"), n = t?.[0];
+	if (t?.length !== 1 || n?.type !== "human" || !Number.isSafeInteger(n.id) || n.id < 0) throw Error("expected exactly one waiting human step with a nonnegative integer index");
+	return n.id;
+}, M = (e, t) => h.gen(function* () {
+	let a = (e, n) => new d({
+		runId: t.runId,
+		reason: e,
+		message: n
+	}), c = yield* _.decodeUnknownEffect(o, { onExcessProperty: "error" })(t).pipe(h.mapError(() => a("invalid-response", "review response requires runId, displayed stepIndex and a valid response")));
+	if (c.response.decision === void 0 && c.response.text === void 0 && c.response.value === void 0) return yield* h.fail(a("invalid-response", "review response must contain a decision, text or value"));
+	let l = e.workflows;
+	if (!l) return yield* h.fail(a("runtime-unavailable", "workflow runtime unavailable; review was not sent"));
+	let p = yield* T(e, t.runId);
+	if (!p) return yield* h.fail(new f({
+		runId: t.runId,
+		message: "run not found"
+	}));
+	let m = p.status;
+	if (m !== "waiting") return yield* h.fail(new u({
+		runId: t.runId,
+		status: m ?? "unknown",
+		message: `run is "${m}", not awaiting a response`
+	}));
+	let g = yield* h.try({
+		try: () => j(p),
+		catch: () => a("invalid-run", "stored run has no unambiguous waiting review")
+	});
+	if (g !== c.stepIndex) return yield* h.fail(new u({
+		runId: t.runId,
+		status: m,
+		message: "this review is no longer waiting; reload the run before answering"
+	}));
+	let v = yield* _.decodeUnknownEffect(_.Struct({
+		runId: _.Literal(t.runId),
+		flowRef: _.NonEmptyString,
+		requestId: _.NonEmptyString,
+		input: _.Record(_.String, _.Unknown),
+		source: _.Literals(["manual", "cron"])
+	}))({
+		...p,
+		runId: p.id
+	}).pipe(h.mapError(() => a("invalid-run", "stored workflow payload is incomplete; review was not sent"))), y = yield* r.executionId(v), b = {
+		...c.response,
+		respondedAt: (/* @__PURE__ */ new Date()).toISOString()
+	}, x = yield* h.tryPromise({
+		try: () => l.signal({
+			workflowName: n,
+			executionId: y
+		}, i(g), b),
+		catch: () => a("delivery-unknown", "review delivery was not confirmed; observe the run before retrying")
+	}), S = yield* _.decodeUnknownEffect(_.Struct({ eventId: _.NonEmptyString }))(x).pipe(h.mapError(() => a("delivery-unknown", "workflow runtime returned no valid review delivery receipt")));
+	return yield* _.decodeUnknownEffect(s)({
+		runId: t.runId,
+		stepIndex: g,
+		executionId: y,
+		eventId: S.eventId,
+		status: "accepted"
+	}).pipe(h.mapError(() => a("delivery-unknown", "workflow runtime returned no valid review delivery receipt")));
+}), N = (e, n) => h.promise(() => e.store.query(S(t).where(b("id", n.id)).descriptor)).pipe(h.map((e) => e[0])), P = (e) => h.promise(() => e.store.query(S(t).descriptor)), F = (e, n) => h.promise(() => e.store.insert(t.tableName, {
+	id: n.id ?? `flow-${C()}`,
+	...n
+})), I = (e, n) => h.promise(() => e.store.update(t.tableName, n.id, n.patch)), L = (e, n) => h.promise(() => e.store.delete(t.tableName, n.id));
+//#endregion
+export { k as cancelFlow, F as createFlow, L as deleteFlow, N as getFlow, i as humanResponseSignalName, D as launchFlow, P as listFlows, M as respondToFlow, O as retryFlow, I as updateFlow, j as waitingStepIndex };

package/dist/registry.js

@@ -0,0 +1,6 @@
+//#region src/registry.ts
+var e = /* @__PURE__ */ new Map(), t = (t) => {
+	e.set(t.name, t);
+}, n = (t) => e.get(t), r = () => [...e.values()], i = () => e.clear();
+//#endregion
+export { i as clearRegistry, n as getRegisteredFlow, r as listRegisteredFlows, t as registerFlow };

package/dist/segments.js

@@ -0,0 +1,33 @@
+//#region src/segments.ts
+var e = (e) => {
+	let t = [], n;
+	if (e.forEach((e, r) => {
+		let i = e.group;
+		i !== void 0 && n !== void 0 && n.group === i ? n.steps.push({
+			index: r,
+			step: e
+		}) : (n !== void 0 && t.push({
+			...n.group === void 0 ? {} : { group: n.group },
+			steps: n.steps
+		}), n = {
+			...i === void 0 ? {} : { group: i },
+			steps: [{
+				index: r,
+				step: e
+			}]
+		});
+	}), n !== void 0) {
+		let e = n;
+		t.push({
+			...e.group === void 0 ? {} : { group: e.group },
+			steps: e.steps
+		});
+	}
+	return t;
+}, t = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) n.group !== void 0 && t.set(n.group, (t.get(n.group) ?? 0) + 1);
+	return [...t.entries()].filter(([, e]) => e > 1).map(([e]) => e).sort();
+};
+//#endregion
+export { e as flowSegments, t as nonContiguousGroups };

package/dist/startReceipt.js

@@ -0,0 +1,12 @@
+import { aiFlowRunsTable as e } from "./table.js";
+import "./workflow.js";
+import { Schema as t } from "effect";
+import { WorkflowRunHandleSchema as n } from "@voltro/protocol";
+//#region src/startReceipt.ts
+var r = async (r, i, a) => {
+	let o = t.decodeUnknownSync(n.pipe(t.check(t.makeFilter((e) => e.workflowName === "flow.run" && e.id.length > 0))))(a);
+	if (await r.store.update(e.tableName, i, { workflowStart: o }) === null) throw Error("flow start receipt could not be recorded; workflow submission may have succeeded");
+	return o;
+};
+//#endregion
+export { r as recordFlowStartReceipt };

package/dist/startReconcile.js

@@ -0,0 +1,81 @@
+import { aiFlowRunsTable as e } from "./table.js";
+import { FLOW_RUN_WORKFLOW as t } from "./workflow.js";
+import { Schema as n } from "effect";
+import { eq as r } from "@voltro/database";
+//#region src/startReconcile.ts
+var i = n.Struct({
+	id: n.NonEmptyString,
+	workflowName: n.Literal(t),
+	status: n.Literal("queued")
+}), a = (e) => ({
+	id: e,
+	workflowName: t,
+	executionId: e,
+	status: "running"
+}), o = (e) => {
+	let t = `flow start was not executed: ${e.reason}`;
+	return e.incumbentExecutionId === null ? e.failureId === null ? t : `${t} (failure report ${e.failureId})` : `${t} (incumbent execution ${e.incumbentExecutionId})`;
+}, s = async (t, s = {}) => {
+	let c = t.workflows;
+	if (!c) throw Error("workflow runtime unavailable; flow starts cannot be reconciled");
+	if (c.startsDeferredUntilCommit === !0) return {
+		examined: 0,
+		accepted: 0,
+		notExecuted: 0,
+		pending: 0,
+		failures: []
+	};
+	let l = s.take ?? 200, u = await t.store.query({
+		table: e.tableName,
+		predicate: r("status", "pending"),
+		order: [],
+		take: l,
+		skip: void 0,
+		projection: void 0
+	}), d = {
+		examined: 0,
+		accepted: 0,
+		notExecuted: 0,
+		pending: 0,
+		failures: []
+	};
+	for (let r of u) {
+		let s = r.id;
+		if (typeof s != "string") continue;
+		let l = n.decodeUnknownOption(i)(r.workflowStart);
+		if (l._tag !== "None") {
+			d.examined++;
+			try {
+				let n = await c.readStart({
+					...l.value,
+					executionId: null
+				});
+				if (n.kind === "pending") {
+					d.pending++;
+					continue;
+				}
+				let r = (/* @__PURE__ */ new Date()).toISOString();
+				if (n.kind === "accepted") {
+					if (await t.store.update(e.tableName, s, { workflowStart: a(n.executionId) }) === null) throw Error("flow run disappeared while recording its accepted start");
+					d.accepted++;
+					continue;
+				}
+				if (await t.store.update(e.tableName, s, {
+					status: "failed",
+					error: "FlowStartNotExecuted",
+					errorMessage: o(n),
+					completedAt: r
+				}) === null) throw Error("flow run disappeared while recording that its start will not execute");
+				d.notExecuted++;
+			} catch (e) {
+				d.failures.push({
+					runId: s,
+					cause: e
+				});
+			}
+		}
+	}
+	return d;
+};
+//#endregion
+export { a as admittedStartHandle, s as reconcileFlowStarts };

package/dist/table.js

@@ -0,0 +1,59 @@
+import { boolean as e, id as t, integer as n, json as r, table as i, text as a, timestamp as o } from "@voltro/database";
+import { tenant as s } from "@voltro/plugin-multitenancy/mixin";
+import { audit as c } from "@voltro/plugin-audit/mixin";
+import { softDelete as l } from "@voltro/plugin-soft-delete/mixin";
+//#region src/table.ts
+var u = i("_voltro_ai_flows", {
+	id: t({ prefix: "aifl" }),
+	name: a(),
+	description: a().nullable(),
+	mode: a().default("deterministic"),
+	status: a().default("draft"),
+	visibility: a().default("private"),
+	orchestratorModel: a().nullable(),
+	orchestratorInstructions: a().nullable(),
+	maxSteps: n().default(30),
+	steps: r().nullable(),
+	inputSchema: r().nullable(),
+	chainTo: r().nullable(),
+	cadence: r().nullable(),
+	humanTimeoutMs: n().nullable(),
+	isEnabled: e().default(!0),
+	metadata: r().nullable(),
+	icon: a().nullable(),
+	color: a().nullable(),
+	avatarUrl: a().nullable(),
+	usageCount: n().default(0),
+	ownerId: a().nullable()
+}).renamedFrom("ai_flows").with(s(), c(), l()).index(["status"]).index(["visibility"]), d = i("_voltro_ai_flow_runs", {
+	id: t({ prefix: "aifr" }),
+	flowRef: a(),
+	flowName: a().nullable(),
+	mode: a().default("deterministic"),
+	status: a().default("pending"),
+	source: a().nullable(),
+	requestId: a(),
+	workflowStart: r().nullable(),
+	input: r().nullable(),
+	output: r().nullable(),
+	steps: r().nullable(),
+	currentStep: n().default(0),
+	totalSteps: n().default(0),
+	humanResponse: r().nullable(),
+	chainPending: r().nullable(),
+	chainRefusal: a().nullable(),
+	costMicroUsd: n().default(0),
+	costCompleteness: a().default("unknown"),
+	durationMs: n().nullable(),
+	error: a().nullable(),
+	errorMessage: a().nullable(),
+	startedAt: o().nullable(),
+	completedAt: o().nullable(),
+	cancelledAt: o().nullable(),
+	sessionId: a().nullable(),
+	sessionName: a().nullable(),
+	ownerId: a().nullable(),
+	metadata: r().nullable()
+}).renamedFrom("ai_flow_runs").with(s(), c()).index(["flowRef"]).index(["status"]).index(["requestId"]), f = [u, d];
+//#endregion
+export { d as aiFlowRunsTable, u as aiFlowsTable, f as aiFlowsTables };

package/dist/textParams.js

@@ -0,0 +1,21 @@
+import { ProviderOptions as e } from "./jsonParams.js";
+import { Effect as t, Schema as n } from "effect";
+//#region src/textParams.ts
+var r = n.Struct({
+	maxTokens: n.optionalKey(n.Int.pipe(n.check(n.isGreaterThan(0)), n.check(n.isLessThanOrEqualTo(2 ** 53 - 1)))),
+	temperature: n.optionalKey(n.Finite.pipe(n.check(n.isGreaterThanOrEqualTo(0)))),
+	providerOptions: n.optionalKey(e)
+}), i = [
+	"maxTokens",
+	"temperature",
+	"providerOptions"
+], a = (e) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return "params must be an object";
+	let t = Object.keys(e), a = t.filter((e) => !i.includes(e)).sort(), o = t.filter((t) => i.includes(t) && n.decodeUnknownOption(r)({ [t]: e[t] })._tag === "None").sort();
+	return [...a.length > 0 ? [`unsupported field${a.length === 1 ? "" : "s"}: ${a.join(", ")}`] : [], ...o.length > 0 ? [`invalid value for: ${o.join(", ")}`] : []].join("; ");
+}, o = (e) => t.try({
+	try: () => n.decodeUnknownSync(r, { onExcessProperty: "error" })(e === void 0 ? {} : e),
+	catch: () => `invalid text params (${a(e)}): expected maxTokens (positive safe integer), temperature (finite nonnegative number), and/or providerOptions (provider-keyed JSON object); other fields are not supported`
+});
+//#endregion
+export { o as decodeTextParams };