@rytass/bpm-core-shared 0.5.0 → 0.5.1

package/src/lib/workflow-toolset.d.ts

@@ -0,0 +1,105 @@
+import { FormDefinitionSchema } from './form';
+import { WorkflowNode } from './workflow';
+import { WorkflowCommandOptions, WorkflowCommandResult, WorkflowDesignerState } from './workflow-command';
+export type { AnyWorkflowCommand } from './workflow-command';
+/**
+ * The LLM-facing toolset for the template designer. It exposes every workflow
+ * mutation as a provider-agnostic tool (JSON Schema input), plus read-only
+ * query tools so the assistant can inspect the graph before acting.
+ *
+ * The same {@link applyWorkflowCommand} reducer powers both the React UI and
+ * this toolset — an LLM driving these tools can do exactly what a user can do
+ * on the canvas, node palette, and property form.
+ *
+ * Usage (Anthropic / AI SDK / OpenAI tool-calling are all compatible):
+ *   1. Advertise `WORKFLOW_TOOLSET` to the model as its tools.
+ *   2. On each tool call, run `executeWorkflowTool(state, name, input, opts)`.
+ *   3. For mutations, persist `result.state`; if `result.effects.layout`, run
+ *      dagre layout (in the React controller); return `snapshot` to the model.
+ */
+/** A minimal JSON Schema object (provider-agnostic tool input contract). */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export type WorkflowToolKind = 'mutation' | 'macro' | 'query';
+export interface WorkflowTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly kind: WorkflowToolKind;
+}
+export declare const WORKFLOW_TOOLSET: readonly WorkflowTool[];
+/** Quick lookup of a tool definition by name. */
+export declare const WORKFLOW_TOOL_BY_NAME: ReadonlyMap<string, WorkflowTool>;
+export interface WorkflowNodeSnapshot {
+    readonly id: string;
+    readonly type: WorkflowNode['type'];
+    readonly typeLabel: string;
+    readonly label: string;
+    readonly summary: string;
+}
+export interface WorkflowEdgeSnapshot {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly isDefault: boolean;
+    readonly conditionLabel: string | null;
+    readonly condition: string | null;
+}
+export interface WorkflowSnapshot {
+    readonly nodes: readonly WorkflowNodeSnapshot[];
+    readonly edges: readonly WorkflowEdgeSnapshot[];
+    readonly selectedNodeId: string | null;
+    readonly selectedEdgeIds: readonly string[];
+    readonly formDefinitionVersionId: string | null;
+    readonly initiatorPolicyCel: string | null;
+    readonly issue: string | null;
+}
+export declare function readWorkflowSnapshot(state: WorkflowDesignerState): WorkflowSnapshot;
+export type WorkflowToolResult = {
+    readonly ok: true;
+    readonly kind: 'mutation' | 'macro';
+    readonly result: WorkflowCommandResult;
+    readonly snapshot: WorkflowSnapshot;
+} | {
+    readonly ok: true;
+    readonly kind: 'query';
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export interface WorkflowDirectoryItem {
+    readonly id: string;
+    readonly name: string;
+    readonly email?: string;
+}
+/**
+ * Host-injected resolver for organisation data. Lets the directory query tools
+ * (`list_org_units` / `list_positions` / `search_members`) surface the real ids
+ * an LLM needs to assign concrete approvers — without the pure toolset knowing
+ * where the data comes from. The React designer backs this with its already
+ * loaded org/position data plus the BPM client's member search.
+ */
+export interface WorkflowDirectory {
+    readonly listOrgUnits: () => Promise<readonly WorkflowDirectoryItem[]>;
+    readonly listPositions: () => Promise<readonly WorkflowDirectoryItem[]>;
+    readonly searchMembers: (query: string) => Promise<readonly WorkflowDirectoryItem[]>;
+}
+export interface ExecuteWorkflowToolOptions extends WorkflowCommandOptions {
+    /**
+     * Host-injected organisation directory. When absent, directory query tools
+     * report `available: false` so the assistant falls back to defaults.
+     */
+    readonly directory?: WorkflowDirectory;
+    /**
+     * Resolves a form version id to its schema (host-managed). Required only if
+     * a tool needs the bound form schema. Not used by the current toolset, which
+     * compiles conditions against the already-bound `state.formSchema`.
+     */
+    readonly resolveFormSchema?: (formDefinitionVersionId: string) => FormDefinitionSchema | null;
+}
+/**
+ * Execute a single LLM tool call against the designer state. Mutations and
+ * macros return the new state + a fresh snapshot; queries return read-only data.
+ * Async because directory query tools may fetch from the host (GraphQL).
+ */
+export declare function executeWorkflowTool(state: WorkflowDesignerState, toolName: string, rawInput: unknown, options?: ExecuteWorkflowToolOptions): Promise<WorkflowToolResult>;