@anchrd/intel-api 0.2.0

package/dist/cli/cli.js

@@ -0,0 +1,141 @@
+import { createBuild } from "../build/build.js";
+import { createPrepare } from "../prepare/prepare.js";
+const interfaces = [
+    { handle: "intel", functions: ["use", "admin"] },
+    { handle: "knowledge", functions: ["read", "create", "write", "share"] },
+    {
+        handle: "flows",
+        functions: ["read", "create", "write", "publish", "run", "approve", "share"],
+    },
+    { handle: "tools", functions: ["read", "test", "execute", "admin"] },
+    { handle: "intel-tools", functions: ["connect"] },
+];
+const usage = `Usage: intel <prepare|bootstrap|build|doctor|reindex>
+  intel prepare    Copy versioned D1 migrations to .intel/migrations
+  intel bootstrap  Idempotently declare Intel interfaces in Gate
+  intel build      Apply intel.json and atomically build the customer UI
+  intel doctor     Check packages, environment, migrations, UI, and Gate interfaces
+  intel reindex    Request a full authorized search-index rebuild`;
+export function createCli(deps) {
+    const envValue = (name) => deps.env[name]?.trim() || null;
+    const fail = (message) => {
+        deps.log(`Error: ${message}`);
+        return 1;
+    };
+    const within = async (work, milliseconds = 10_000) => {
+        let timer;
+        try {
+            return await Promise.race([
+                work,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error("operation timed out")), milliseconds);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    async function bootstrap() {
+        const gateUrl = envValue("GATE_URL");
+        const serviceKey = envValue("GATE_SERVICE_KEY") ?? envValue("GATE_KEY");
+        if (!gateUrl || !serviceKey) {
+            return fail("GATE_URL and GATE_SERVICE_KEY must be set.");
+        }
+        const gate = deps.createGateInterfaces(gateUrl, serviceKey);
+        for (const entry of interfaces)
+            await gate.set(entry.handle, [...entry.functions]);
+        deps.log(`Declared ${interfaces.length} Intel interfaces in Gate. No grants were changed.`);
+        return 0;
+    }
+    async function doctor() {
+        const failures = [];
+        const gateUrl = envValue("GATE_URL");
+        const intelUrl = envValue("INTEL_URL");
+        const serviceKey = envValue("GATE_SERVICE_KEY") ?? envValue("GATE_KEY");
+        const sessionSecret = envValue("INTEL_SESSION_SECRET");
+        const toolSourceOrigins = envValue("TOOL_SOURCE_ORIGINS");
+        const portalUrl = envValue("MCP_PORTAL_URL");
+        if (!gateUrl)
+            failures.push("GATE_URL is missing");
+        if (!intelUrl)
+            failures.push("INTEL_URL is missing");
+        if (!serviceKey)
+            failures.push("GATE_SERVICE_KEY is missing");
+        if (!toolSourceOrigins)
+            failures.push("TOOL_SOURCE_ORIGINS is missing");
+        // Tools are optional for a deployment that only uses Knowledge and Flows, so a missing portal
+        // is reported as a warning rather than a failure.
+        if (!portalUrl) {
+            deps.log("Note: MCP_PORTAL_URL is unset, so the Tools area stays empty.");
+        }
+        else if (toolSourceOrigins && !toolSourceOrigins.includes(new URL(portalUrl).origin)) {
+            failures.push("MCP_PORTAL_URL origin is missing from TOOL_SOURCE_ORIGINS");
+        }
+        if (!sessionSecret || new TextEncoder().encode(sessionSecret).byteLength < 32) {
+            failures.push("INTEL_SESSION_SECRET must contain at least 32 bytes");
+        }
+        if (!(await deps.resolveUi()))
+            failures.push("@anchrd/intel-ui is not installed");
+        if (!(await deps.resolveMigrations()))
+            failures.push("Intel migrations are not installed");
+        if (gateUrl && serviceKey) {
+            try {
+                const current = await within(deps.createGateInterfaces(gateUrl, serviceKey).list());
+                for (const expected of interfaces) {
+                    const actual = current.find((entry) => entry.handle === expected.handle);
+                    const missing = expected.functions.filter((fn) => !actual?.functions.includes(fn));
+                    if (missing.length)
+                        failures.push(`Gate interface ${expected.handle} misses ${missing}`);
+                }
+            }
+            catch {
+                failures.push("Gate interface check failed");
+            }
+        }
+        if (failures.length) {
+            for (const failure of failures)
+                deps.log(`FAIL ${failure}`);
+            return 1;
+        }
+        deps.log("OK Intel packages, configuration, and Gate interfaces are ready.");
+        return 0;
+    }
+    async function reindex() {
+        const intelUrl = envValue("INTEL_URL")?.replace(/\/+$/, "");
+        const token = envValue("INTEL_OPERATOR_TOKEN");
+        if (!intelUrl || !token) {
+            return fail("INTEL_URL and a short-lived INTEL_OPERATOR_TOKEN must be set.");
+        }
+        const response = await deps.fetch(`${intelUrl}/api/v1/search/reindex`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: "{}",
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            return fail(`reindex responded with ${response.status}`);
+        deps.log("Intel accepted the reindex request.");
+        return 0;
+    }
+    return {
+        async run(argv) {
+            switch (argv[0]) {
+                case "prepare":
+                    return await createPrepare(deps).prepare();
+                case "bootstrap":
+                    return await bootstrap();
+                case "build":
+                    return await createBuild(deps).build();
+                case "doctor":
+                    return await doctor();
+                case "reindex":
+                    return await reindex();
+                default:
+                    deps.log(usage);
+                    return argv[0] ? 1 : 0;
+            }
+        },
+    };
+}

package/dist/cli/cli.types.d.ts

@@ -0,0 +1,14 @@
+import type { BuildDeps } from "../build/build.types.js";
+import type { PrepareDeps } from "../prepare/prepare.types.js";
+export interface GateInterfaces {
+    list(): Promise<Array<{
+        handle: string;
+        functions: string[];
+    }>>;
+    set(handle: string, functions: string[]): Promise<unknown>;
+}
+export interface CliDeps extends BuildDeps, PrepareDeps {
+    env: Record<string, string | undefined>;
+    fetch: typeof fetch;
+    createGateInterfaces(url: string, serviceKey: string): GateInterfaces;
+}

package/dist/cli/cli.types.js

@@ -0,0 +1 @@
+export {};

package/dist/flows/flows.d.ts

@@ -0,0 +1,4 @@
+import type { FlowGraph } from "@anchrd/intel-contract";
+import type { CompiledFlow, FlowDeps, FlowService } from "./flows.types.js";
+export declare function compileFlow(graph: FlowGraph): CompiledFlow;
+export declare function createFlows(deps: FlowDeps): FlowService;

package/dist/flows/flows.js

@@ -0,0 +1,409 @@
+import { IntelError } from "../shared/intel-error/intel-error.js";
+function invalid(detail) {
+    throw new IntelError(400, "flow_graph_invalid", detail);
+}
+export function compileFlow(graph) {
+    const nodes = new Map();
+    for (const node of graph.nodes) {
+        if (nodes.has(node.id))
+            invalid(`Duplicate node ID: ${node.id}`);
+        nodes.set(node.id, node);
+    }
+    const edgeIds = new Set();
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const edge of graph.edges) {
+        if (edgeIds.has(edge.id))
+            invalid(`Duplicate edge ID: ${edge.id}`);
+        edgeIds.add(edge.id);
+        if (!nodes.has(edge.source) || !nodes.has(edge.target))
+            invalid(`Dangling edge: ${edge.id}`);
+        incoming.set(edge.target, (incoming.get(edge.target) ?? 0) + 1);
+        outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]);
+    }
+    const triggers = graph.nodes.filter((node) => node.kind === "trigger");
+    if (triggers.length !== 1)
+        invalid("A flow requires exactly one trigger");
+    if (!graph.nodes.some((node) => node.kind === "output"))
+        invalid("A flow requires an output");
+    const trigger = triggers[0];
+    if (!trigger)
+        invalid("A flow requires exactly one trigger");
+    for (const node of graph.nodes) {
+        const parents = incoming.get(node.id) ?? 0;
+        const children = outgoing.get(node.id) ?? [];
+        if (node.kind === "trigger" && parents !== 0)
+            invalid("The trigger cannot have an incoming edge");
+        if (node.kind !== "trigger" && parents !== 1) {
+            invalid(`Node ${node.id} requires exactly one incoming edge`);
+        }
+        if (node.kind === "output" && children.length !== 0)
+            invalid(`Output ${node.id} must be terminal`);
+        if (node.kind === "condition" || node.kind === "approval") {
+            if (children.length < 2)
+                invalid(`Node ${node.id} requires at least two branches`);
+            const handles = new Set(children.map((edge) => edge.sourceHandle));
+            if (handles.has(null) || handles.size !== children.length) {
+                invalid(`Node ${node.id} requires unique branch handles`);
+            }
+        }
+        else if (node.kind !== "output") {
+            if (children.length !== 1)
+                invalid(`Node ${node.id} requires exactly one outgoing edge`);
+            if (children[0]?.sourceHandle !== null)
+                invalid(`Node ${node.id} cannot define a branch handle`);
+        }
+    }
+    const visited = new Set();
+    const active = new Set();
+    function visit(nodeId) {
+        if (active.has(nodeId))
+            invalid("Flow graphs cannot contain cycles");
+        if (visited.has(nodeId))
+            return;
+        active.add(nodeId);
+        for (const edge of outgoing.get(nodeId) ?? [])
+            visit(edge.target);
+        active.delete(nodeId);
+        visited.add(nodeId);
+    }
+    visit(trigger.id);
+    if (visited.size !== graph.nodes.length)
+        invalid("Every node must be reachable from the trigger");
+    return { graph, triggerId: trigger.id };
+}
+function nodeFor(version, nodeId) {
+    return nodeId ? (version.graph.nodes.find((node) => node.id === nodeId) ?? null) : null;
+}
+export function createFlows(deps) {
+    async function requireFlow(actor, flowId) {
+        const flow = await deps.repository.getVisible(actor, flowId);
+        if (!flow || flow.archivedAt)
+            throw new IntelError(404, "flow_not_found", "Flow was not found");
+        return flow;
+    }
+    // Every surface maps the Gate capability into the actor, so the rule lives here once instead of
+    // being restated per surface. Checked before any storage access.
+    function requireRun(actor) {
+        if (!actor.canRun) {
+            throw new IntelError(403, "flow_run_forbidden", "Flow run permission is required");
+        }
+    }
+    async function requireEdit(actor, flowId) {
+        const flow = await requireFlow(actor, flowId);
+        if (!(await deps.repository.canEdit(actor, flowId))) {
+            throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+        }
+        return flow;
+    }
+    async function requireManage(actor, flowId) {
+        const flow = await requireFlow(actor, flowId);
+        if (!(await deps.repository.canManage(actor, flowId))) {
+            throw new IntelError(403, "flow_manage_forbidden", "Flow sharing cannot be managed");
+        }
+        return flow;
+    }
+    async function requireVersion(versionId, flowId) {
+        const version = await deps.repository.getVersion(versionId);
+        if (!version || (flowId && version.flowId !== flowId)) {
+            throw new IntelError(404, "flow_version_not_found", "Flow version was not found");
+        }
+        return version;
+    }
+    async function step(actor, run) {
+        await requireFlow(actor, run.flowId);
+        const version = await requireVersion(run.versionId, run.flowId);
+        return { run, node: nodeFor(version, run.currentNodeId) };
+    }
+    return {
+        async list(actor) {
+            return { items: await deps.repository.listVisible(actor) };
+        },
+        async get(actor, flowId) {
+            const flow = await requireFlow(actor, flowId);
+            return {
+                flow,
+                version: flow.currentVersionId
+                    ? await requireVersion(flow.currentVersionId, flow.id)
+                    : null,
+            };
+        },
+        async create(actor, input) {
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.create", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, replayed);
+            const occurredAt = deps.now().toISOString();
+            return await deps.repository.insertFlow({
+                flow: {
+                    id: deps.id(),
+                    title: input.title,
+                    description: input.description,
+                    ownerId: actor.id,
+                    currentVersionId: null,
+                    publishedVersionId: null,
+                    createdAt: occurredAt,
+                    updatedAt: occurredAt,
+                    archivedAt: null,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        async save(actor, input) {
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
+            if (replayed) {
+                const version = await requireVersion(replayed, input.flowId);
+                return { flow: await requireFlow(actor, input.flowId), version };
+            }
+            const flow = await requireEdit(actor, input.flowId);
+            compileFlow(input.graph);
+            if (flow.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "flow_version_conflict", "Flow changed since it was loaded");
+            }
+            const previous = flow.currentVersionId
+                ? await requireVersion(flow.currentVersionId, flow.id)
+                : null;
+            const occurredAt = deps.now().toISOString();
+            const version = {
+                id: deps.id(),
+                flowId: flow.id,
+                sequence: (previous?.sequence ?? 0) + 1,
+                graph: input.graph,
+                createdBy: actor.id,
+                createdAt: occurredAt,
+            };
+            const result = await deps.repository.insertVersion({
+                version,
+                baseVersionId: input.baseVersionId,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (result === "conflict") {
+                throw new IntelError(409, "flow_version_conflict", "Flow changed since it was loaded");
+            }
+            return { flow: await requireFlow(actor, flow.id), version };
+        },
+        async publish(actor, input) {
+            const flow = await requireEdit(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.publish", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, flow.id);
+            const version = await requireVersion(input.versionId, flow.id);
+            compileFlow(version.graph);
+            for (const node of version.graph.nodes) {
+                if (node.kind === "knowledge") {
+                    for (const resourceId of node.configuration.resourceIds) {
+                        if (!(await deps.knowledgeExists(actor, resourceId))) {
+                            throw new IntelError(409, "flow_knowledge_unavailable", `Knowledge reference is unavailable: ${resourceId}`);
+                        }
+                    }
+                }
+                if (node.kind === "tool") {
+                    const fingerprint = await deps.toolFingerprint(actor, node.configuration.toolName);
+                    if (!fingerprint) {
+                        throw new IntelError(409, "flow_tool_unavailable", `Tool is unavailable: ${node.label}`);
+                    }
+                    if (node.configuration.fingerprint !== fingerprint) {
+                        throw new IntelError(409, "flow_tool_schema_changed", `Review the current schema before publishing: ${node.label}`);
+                    }
+                }
+            }
+            const published = await deps.repository.publish({
+                flowId: flow.id,
+                versionId: version.id,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+            });
+            if (!published)
+                throw new IntelError(409, "flow_publish_conflict", "Flow could not be published");
+            return await requireFlow(actor, flow.id);
+        },
+        async start(actor, input) {
+            requireRun(actor);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.run", input.idempotencyKey);
+            if (replayed) {
+                const run = await deps.repository.getRunVisible(actor, replayed);
+                if (run) {
+                    if (run.status === "running" || run.status === "queued")
+                        await deps.runtime.start(run.id);
+                    return await step(actor, run);
+                }
+            }
+            const flow = await requireFlow(actor, input.flowId);
+            if (!flow.publishedVersionId) {
+                throw new IntelError(409, "flow_not_published", "Flow has no published version");
+            }
+            const version = await requireVersion(flow.publishedVersionId, flow.id);
+            const compiled = compileFlow(version.graph);
+            const first = version.graph.edges.find((edge) => edge.source === compiled.triggerId)?.target;
+            if (!first)
+                invalid("The trigger requires an outgoing edge");
+            // The flow may have been built by someone with wider portal access. Naming the missing tools
+            // before the first step beats failing halfway through with a portal error the user cannot place.
+            const missing = await deps.unavailableTools(actor, version.graph.nodes
+                .filter((node) => node.kind === "tool")
+                .map((node) => (node.kind === "tool" ? node.configuration.toolName : "")));
+            if (missing.length) {
+                throw new IntelError(403, "flow_tools_unavailable", `You cannot reach these tools: ${missing.join(", ")}`);
+            }
+            const occurredAt = deps.now().toISOString();
+            const run = {
+                id: deps.id(),
+                flowId: flow.id,
+                versionId: version.id,
+                status: "running",
+                currentNodeId: first,
+                input: input.input,
+                output: null,
+                error: null,
+                initiatedBy: actor.id,
+                createdAt: occurredAt,
+                updatedAt: occurredAt,
+                completedAt: null,
+            };
+            const inserted = await deps.repository.insertRun({
+                run,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            await deps.runtime.start(inserted.id);
+            return await step(actor, inserted);
+        },
+        async getRun(actor, runId) {
+            const run = await deps.repository.getRunVisible(actor, runId);
+            if (!run)
+                throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            return await step(actor, run);
+        },
+        async completeStep(actor, input) {
+            requireRun(actor);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.complete", input.idempotencyKey);
+            if (replayed) {
+                const run = await deps.repository.getRunVisible(actor, replayed);
+                if (run)
+                    return await step(actor, run);
+            }
+            const current = await deps.repository.getRunVisible(actor, input.runId);
+            if (!current)
+                throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            if (current.status !== "running" && current.status !== "waiting") {
+                throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
+            }
+            if (current.currentNodeId !== input.nodeId) {
+                throw new IntelError(409, "flow_step_conflict", "A different step is currently active");
+            }
+            const version = await requireVersion(current.versionId, current.flowId);
+            const node = nodeFor(version, input.nodeId);
+            if (!node) {
+                throw new IntelError(500, "flow_version_corrupt", "Current run node is missing from the immutable version");
+            }
+            if (node.kind === "approval" && !actor.canApprove) {
+                throw new IntelError(403, "flow_approval_forbidden", "Approval permission is required");
+            }
+            const occurredAt = deps.now().toISOString();
+            let status = "running";
+            let currentNodeId = null;
+            let output = current.output;
+            let error = null;
+            let completedAt = null;
+            if (input.outcome === "failed") {
+                status = "failed";
+                error = input.error ?? "Flow step failed";
+                completedAt = occurredAt;
+            }
+            else if (node.kind === "output") {
+                status = "completed";
+                output = input.output;
+                completedAt = occurredAt;
+            }
+            else {
+                const edges = version.graph.edges.filter((edge) => edge.source === node.id);
+                const edge = node.kind === "condition" || node.kind === "approval"
+                    ? edges.find((candidate) => candidate.sourceHandle === input.branch)
+                    : edges[0];
+                if (!edge) {
+                    throw new IntelError(400, "flow_branch_invalid", "A valid branch is required");
+                }
+                currentNodeId = edge.target;
+            }
+            const next = {
+                ...current,
+                status,
+                currentNodeId,
+                output,
+                error,
+                updatedAt: occurredAt,
+                completedAt,
+            };
+            const advanced = await deps.repository.advanceRun({
+                run: next,
+                expectedNodeId: input.nodeId,
+                actorId: actor.id,
+                stepId: deps.id(),
+                outcome: input.outcome,
+                branch: input.branch,
+                output: input.output,
+                error: input.error,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (advanced === "conflict") {
+                throw new IntelError(409, "flow_step_conflict", "Flow step was already completed");
+            }
+            await deps.runtime.signal(next.id);
+            return await step(actor, next);
+        },
+        async listGrants(actor, flowId) {
+            await requireManage(actor, flowId);
+            return { items: await deps.repository.listGrants(flowId) };
+        },
+        async share(actor, input) {
+            await requireManage(actor, input.resourceId);
+            const replayedId = await deps.repository.findIdempotent(actor.id, "flows.share", input.idempotencyKey);
+            if (replayedId) {
+                const replayed = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === replayedId);
+                if (replayed)
+                    return replayed;
+            }
+            const principal = input.principal.type === "email"
+                ? { type: "email", email: input.principal.email.toLowerCase() }
+                : input.principal;
+            const createdAt = deps.now().toISOString();
+            return await deps.repository.setGrant({
+                grant: {
+                    id: deps.id(),
+                    resourceId: input.resourceId,
+                    principal,
+                    role: input.role,
+                    expiresAt: input.expiresAt,
+                    createdBy: actor.id,
+                    createdAt,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        async revokeGrant(actor, input) {
+            await requireManage(actor, input.resourceId);
+            const replayed = await deps.repository.findIdempotentRevocation(actor.id, input.idempotencyKey);
+            if (replayed !== null)
+                return { revoked: replayed };
+            return {
+                revoked: await deps.repository.revokeGrant({
+                    flowId: input.resourceId,
+                    grantId: input.grantId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
+    };
+}

package/dist/flows/flows.types.d.ts

@@ -0,0 +1,108 @@
+import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowRun, FlowRunStep, FlowVersion, PublishFlowInput, ResourceGrant, RevokeFlowGrantInput, SaveFlowVersionInput, ShareFlowInput, StartFlowRunInput } from "@anchrd/intel-contract";
+export interface FlowActor {
+    id: string;
+    email: string;
+    canRun: boolean;
+    canApprove: boolean;
+}
+export type FlowOperation = "flows.create" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.share" | "flows.revoke";
+export interface FlowRepository {
+    listVisible(actor: FlowActor): Promise<Flow[]>;
+    getVisible(actor: FlowActor, flowId: string): Promise<Flow | null>;
+    canEdit(actor: FlowActor, flowId: string): Promise<boolean>;
+    canManage(actor: FlowActor, flowId: string): Promise<boolean>;
+    findIdempotent(actorId: string, operation: FlowOperation, key: string): Promise<string | null>;
+    findIdempotentRevocation(actorId: string, key: string): Promise<boolean | null>;
+    insertFlow(input: {
+        flow: Flow;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<Flow>;
+    getVersion(versionId: string): Promise<FlowVersion | null>;
+    insertVersion(input: {
+        version: FlowVersion;
+        baseVersionId: string | null;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"saved" | "conflict">;
+    publish(input: {
+        flowId: string;
+        versionId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    listGrants(flowId: string): Promise<ResourceGrant[]>;
+    setGrant(input: {
+        grant: ResourceGrant;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeGrant(input: {
+        flowId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    insertRun(input: {
+        run: FlowRun;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<FlowRun>;
+    getRunVisible(actor: FlowActor, runId: string): Promise<FlowRun | null>;
+    advanceRun(input: {
+        run: FlowRun;
+        expectedNodeId: string;
+        actorId: string;
+        stepId: string;
+        outcome: "completed" | "failed";
+        branch: string | null;
+        output: unknown;
+        error: string | null;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"advanced" | "conflict">;
+}
+export interface FlowRuntime {
+    start(runId: string): Promise<void>;
+    signal(runId: string): Promise<void>;
+}
+export interface FlowDeps {
+    repository: FlowRepository;
+    runtime: FlowRuntime;
+    id(): string;
+    now(): Date;
+    knowledgeExists(actor: FlowActor, resourceId: string): Promise<boolean>;
+    toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
+    unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
+}
+export interface FlowService {
+    list(actor: FlowActor): Promise<{
+        items: Flow[];
+    }>;
+    get(actor: FlowActor, flowId: string): Promise<FlowDocument>;
+    create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
+    save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
+    publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;
+    start(actor: FlowActor, input: StartFlowRunInput): Promise<FlowRunStep>;
+    getRun(actor: FlowActor, runId: string): Promise<FlowRunStep>;
+    completeStep(actor: FlowActor, input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
+    listGrants(actor: FlowActor, flowId: string): Promise<{
+        items: ResourceGrant[];
+    }>;
+    share(actor: FlowActor, input: ShareFlowInput): Promise<ResourceGrant>;
+    revokeGrant(actor: FlowActor, input: RevokeFlowGrantInput): Promise<{
+        revoked: boolean;
+    }>;
+}
+export interface CompiledFlow {
+    graph: FlowGraph;
+    triggerId: string;
+}

package/dist/flows/flows.types.js

@@ -0,0 +1 @@
+export {};