@dazl/api-client 1.0.43 → 1.0.45

package/dist/workflow-document.d.ts

@@ -0,0 +1,243 @@
+import { z } from "zod";
+/** The only schema version there has ever been. Interactive fields are ordinary optional fields. */
+export declare const WORKFLOW_DOCUMENT_SCHEMA_VERSION = "1";
+/** Directory the editor creates workflow files in. Discovery is by extension, not by directory. */
+export declare const WORKFLOWS_DIR = "workflows";
+export declare const WORKFLOW_FILE_EXTENSION = ".flow.json";
+/** How a run can start. A closed set: nothing else starts a run, and there is no schedule trigger. */
+export declare const TRIGGER_SOURCES: readonly ["workspace-prompt", "chat-prompt", "chat-agent-tool"];
+export type TriggerSource = (typeof TRIGGER_SOURCES)[number];
+/** A non-empty path relative to the project root that cannot leave it. */
+export declare const projectRelativePathSchema: z.ZodString;
+/**
+ * What every node produces. The same shape for every node in every workflow — it is not authored and
+ * is not part of the document. A step that needs to hand on anything richer than prose writes a file
+ * and names it here.
+ */
+export declare const workflowNodeOutputSchema: z.ZodObject<{
+    text: z.ZodString;
+    files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    changes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        dirName: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        commits: z.ZodNumber;
+        files: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WorkflowNodeOutput = z.infer<typeof workflowNodeOutputSchema>;
+/** One reviewer on a review node: an agent, optionally speaking for a person. */
+export declare const workflowReviewerSchema: z.ZodObject<{
+    agent: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+    onBehalfOf: z.ZodOptional<z.ZodString>;
+    conversationRole: z.ZodOptional<z.ZodEnum<{
+        personal: "personal";
+        workspace: "workspace";
+    }>>;
+}, z.core.$strip>;
+export type WorkflowReviewer = z.infer<typeof workflowReviewerSchema>;
+export declare const workflowNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    manualPosition: z.ZodOptional<z.ZodBoolean>;
+    size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    nextStep: z.ZodOptional<z.ZodString>;
+    skippable: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"trigger">;
+    source: z.ZodEnum<{
+        "workspace-prompt": "workspace-prompt";
+        "chat-prompt": "chat-prompt";
+        "chat-agent-tool": "chat-agent-tool";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    manualPosition: z.ZodOptional<z.ZodBoolean>;
+    size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    nextStep: z.ZodOptional<z.ZodString>;
+    skippable: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"work">;
+    interaction: z.ZodOptional<z.ZodEnum<{
+        interactive: "interactive";
+        automatic: "automatic";
+    }>>;
+    agent: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    manualPosition: z.ZodOptional<z.ZodBoolean>;
+    size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    nextStep: z.ZodOptional<z.ZodString>;
+    skippable: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"review">;
+    interaction: z.ZodOptional<z.ZodEnum<{
+        interactive: "interactive";
+        automatic: "automatic";
+    }>>;
+    reviewers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        prompt: z.ZodOptional<z.ZodString>;
+        onBehalfOf: z.ZodOptional<z.ZodString>;
+        conversationRole: z.ZodOptional<z.ZodEnum<{
+            personal: "personal";
+            workspace: "workspace";
+        }>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>], "kind">;
+export type WorkflowNode = z.infer<typeof workflowNodeSchema>;
+/**
+ * Kinds that can only ever *begin* a chain: nothing may name one as its `nextStep`.
+ *
+ * A named list rather than a `=== "trigger"` written out wherever the question comes up, because it
+ * is asked in three places that must agree - `validateWorkflowChain` below, the editor's chain
+ * mutations, and the editor's add menus - and two of those are in another repository reaching this
+ * file through the SDK. It is a list rather than a single value because several triggers in one
+ * workflow are coming, each starting its own chain, and because a second head-only kind would then
+ * be one entry here rather than a fourth copy of the same comparison.
+ */
+export declare const CHAIN_HEAD_KINDS: readonly WorkflowNode["kind"][];
+/** Whether a node of this kind can only start a chain. `undefined` - an unknown node - is not one. */
+export declare function isChainHeadKind(kind: string | undefined): boolean;
+export declare const workflowDocumentSchema: z.ZodObject<{
+    schemaVersion: z.ZodOptional<z.ZodLiteral<"1">>;
+    meta: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    nodes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        manualPosition: z.ZodOptional<z.ZodBoolean>;
+        size: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        nextStep: z.ZodOptional<z.ZodString>;
+        skippable: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"trigger">;
+        source: z.ZodEnum<{
+            "workspace-prompt": "workspace-prompt";
+            "chat-prompt": "chat-prompt";
+            "chat-agent-tool": "chat-agent-tool";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        manualPosition: z.ZodOptional<z.ZodBoolean>;
+        size: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        nextStep: z.ZodOptional<z.ZodString>;
+        skippable: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"work">;
+        interaction: z.ZodOptional<z.ZodEnum<{
+            interactive: "interactive";
+            automatic: "automatic";
+        }>>;
+        agent: z.ZodString;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        manualPosition: z.ZodOptional<z.ZodBoolean>;
+        size: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        nextStep: z.ZodOptional<z.ZodString>;
+        skippable: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"review">;
+        interaction: z.ZodOptional<z.ZodEnum<{
+            interactive: "interactive";
+            automatic: "automatic";
+        }>>;
+        reviewers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            prompt: z.ZodOptional<z.ZodString>;
+            onBehalfOf: z.ZodOptional<z.ZodString>;
+            conversationRole: z.ZodOptional<z.ZodEnum<{
+                personal: "personal";
+                workspace: "workspace";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>], "kind">>>;
+}, z.core.$strip>;
+export type WorkflowDocument = z.infer<typeof workflowDocumentSchema>;
+export type WorkflowDocumentInput = z.input<typeof workflowDocumentSchema>;
+/** Inspects the whole document. Execution must first restrict this to its selected reachable chain. */
+export declare function isInteractiveWorkflowDocument(document: WorkflowDocument): boolean;
+export interface WorkflowDocumentError {
+    path: string;
+    message: string;
+}
+export type WorkflowDocumentValidation = {
+    valid: true;
+    document: WorkflowDocument;
+} | {
+    valid: false;
+    errors: WorkflowDocumentError[];
+};
+export declare function validateWorkflowDocument(value: unknown): WorkflowDocumentValidation;
+export interface WorkflowChainWarning {
+    nodeId: string;
+    message: string;
+}
+/**
+ * Chain integrity, reported separately from schema validity and deliberately as warnings.
+ *
+ * A half-built workflow is a normal state to be in while authoring — a node whose `nextStep` is not
+ * written yet must not make the file invalid. Step 2's sync is where these become failures.
+ */
+export declare function validateWorkflowChain(nodes: readonly WorkflowNode[]): WorkflowChainWarning[];
+export declare function createDefaultWorkflowDocument(name: string): WorkflowDocumentInput;
+/**
+ * Filename for a workflow, derived from its display name.
+ *
+ * Throws rather than returning a bare extension for a name with no ASCII alphanumerics, matching
+ * `CanvasManager.createCanvasFileName`. Step 1a's agent equivalent shipped without this guard and a
+ * non-Latin name silently wrote a dotfile.
+ */
+export declare function toSafeWorkflowFileName(name: string): string;
+//# sourceMappingURL=workflow-document.d.ts.map

package/dist/workflow-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-document.d.ts","sourceRoot":"","sources":["../src/workflow-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oGAAoG;AACpG,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,mGAAmG;AACnG,eAAO,MAAM,aAAa,cAAc,CAAC;AACzC,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,sGAAsG;AACtG,eAAO,MAAM,eAAe,iEAAkE,CAAC;AAC/F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAuB7D,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,aAA4B,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;iBA2BnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAmB1E,iFAAiF;AACjF,eAAO,MAAM,sBAAsB;;;;;;;;iBAcjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAyB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAgB,CAAC;AAE7E,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEjE;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE3E,uGAAuG;AACvG,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAEjF;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,0BAA0B,GACpC;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAAC;AAElG,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAYnF;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,oBAAoB,EAAE,CAqF5F;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAkBjF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW3D"}

package/dist/workflow-document.js

@@ -0,0 +1,282 @@
+import { z } from "zod";
+/** The only schema version there has ever been. Interactive fields are ordinary optional fields. */
+export const WORKFLOW_DOCUMENT_SCHEMA_VERSION = "1";
+/** Directory the editor creates workflow files in. Discovery is by extension, not by directory. */
+export const WORKFLOWS_DIR = "workflows";
+export const WORKFLOW_FILE_EXTENSION = ".flow.json";
+/** How a run can start. A closed set: nothing else starts a run, and there is no schedule trigger. */
+export const TRIGGER_SOURCES = ["workspace-prompt", "chat-prompt", "chat-agent-tool"];
+/**
+ * Whether a path stays inside the project root it is resolved against: not an absolute POSIX, drive
+ * or UNC path, not a URL, no `..` segment, no NUL byte. Both `/` and `\` count as separators, so the
+ * guarantee holds for a consumer on Windows too. A backslash is otherwise allowed, because git
+ * C-quotes a non-ASCII name (`"\303\251.txt"`) and observed paths carry that verbatim. `.` and empty
+ * segments cannot escape, so a `./` prefix or a doubled slash is accepted rather than rejected.
+ */
+function staysInProjectRoot(path) {
+    return (!/^[/\\]/.test(path) &&
+        !/^[a-z]:/i.test(path) &&
+        !/^[a-z][a-z\d+.-]*:\/\//i.test(path) &&
+        !path.split(/[/\\]/).includes("..") &&
+        !path.includes("\0"));
+}
+const relativePathSchema = z.string().refine(staysInProjectRoot, {
+    message: "Must be a project-relative path: not absolute, not a URL, and without '..' segments",
+});
+/** A non-empty path relative to the project root that cannot leave it. */
+export const projectRelativePathSchema = relativePathSchema.min(1);
+/**
+ * What every node produces. The same shape for every node in every workflow — it is not authored and
+ * is not part of the document. A step that needs to hand on anything richer than prose writes a file
+ * and names it here.
+ */
+export const workflowNodeOutputSchema = z.object({
+    text: z.string(),
+    /** Project-relative paths. Never absolute, never a URL, never escaping the root. */
+    files: z.array(projectRelativePathSchema).default([]),
+    /**
+     * What the executor observed this step change, one entry per repository whose head moved.
+     *
+     * Written by the executor after the agent's own output, never by the agent: `text` and `files`
+     * are what a step says it did, and this is what it was seen to do. Optional because an output
+     * stored before this existed must still parse, and because a step that moved no head records
+     * nothing at all. Absent therefore means "nothing was observed", which covers both a step that
+     * changed nothing and a step nobody was watching - the two are deliberately not distinguished
+     * here. What is kept distinct is absent versus an empty array, which no producer ever writes.
+     */
+    changes: z
+        .array(z.object({
+        /** Directory under the project root; '' when the project root is itself the repo. */
+        dirName: relativePathSchema,
+        from: z.string(),
+        to: z.string(),
+        commits: z.number().int().nonnegative(),
+        /** Project-relative, as `getChangedFilesBetween` reports them. */
+        files: z.array(projectRelativePathSchema),
+    }))
+        .optional(),
+});
+const nodePositionSchema = z.object({ x: z.number(), y: z.number() });
+const nodeSizeSchema = z.object({ width: z.number(), height: z.number() });
+const baseNodeSchema = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+    description: z.string().optional(),
+    position: nodePositionSchema,
+    /** Set once a user drags a node, so auto-layout stops moving it. */
+    manualPosition: z.boolean().optional(),
+    size: nodeSizeSchema.optional(),
+    /** The one node that follows this one. Absent means the run ends here. */
+    nextStep: z.string().optional(),
+    skippable: z.boolean().default(false),
+});
+/** One reviewer on a review node: an agent, optionally speaking for a person. */
+export const workflowReviewerSchema = z.object({
+    /**
+     * An agent document's `meta.name`. Deliberately not `.min(1)`, for the same reason as the `work`
+     * node's `agent` field below: a reviewer can be added before its agent is picked, and rejecting
+     * `""` here would make the whole document non-conforming over the step the user just touched.
+     * `validateWorkflowChain` warns about an empty reviewer agent; sync time is where it becomes an
+     * error.
+     */
+    agent: z.string(),
+    prompt: z.string().optional(),
+    /** Email of the person this reviewer represents, matching how rule owners are named. */
+    onBehalfOf: z.string().optional(),
+    /** Omission means personal. Only an explicit designation makes a conversation workspace-visible. */
+    conversationRole: z.enum(["personal", "workspace"]).optional(),
+});
+export const workflowNodeSchema = z.discriminatedUnion("kind", [
+    baseNodeSchema.extend({
+        kind: z.literal("trigger"),
+        source: z.enum(TRIGGER_SOURCES),
+    }),
+    baseNodeSchema.extend({
+        kind: z.literal("work"),
+        interaction: z.enum(["automatic", "interactive"]).optional(),
+        /**
+         * An agent document's `meta.name`. Resolved at sync time, warned about while authoring -
+         * deliberately not `.min(1)`. A work step exists before an agent is chosen for it, and a
+         * `.min(1)` here would make the whole document non-conforming the instant such a step is
+         * created, collapsing the panel around the step the user just added. `""` is a safe sentinel
+         * for "not picked yet" because every other agent reference in this file is `.min(1)`, so no
+         * real agent can be named the empty string. `validateWorkflowChain` warns about it instead.
+         */
+        agent: z.string(),
+        /** Extra instruction for this step, appended to the agent's own system prompt. */
+        prompt: z.string().optional(),
+    }),
+    baseNodeSchema.extend({
+        kind: z.literal("review"),
+        interaction: z.enum(["automatic", "interactive"]).optional(),
+        reviewers: z.array(workflowReviewerSchema).default([]),
+    }),
+]);
+/**
+ * Kinds that can only ever *begin* a chain: nothing may name one as its `nextStep`.
+ *
+ * A named list rather than a `=== "trigger"` written out wherever the question comes up, because it
+ * is asked in three places that must agree - `validateWorkflowChain` below, the editor's chain
+ * mutations, and the editor's add menus - and two of those are in another repository reaching this
+ * file through the SDK. It is a list rather than a single value because several triggers in one
+ * workflow are coming, each starting its own chain, and because a second head-only kind would then
+ * be one entry here rather than a fourth copy of the same comparison.
+ */
+export const CHAIN_HEAD_KINDS = ["trigger"];
+/** Whether a node of this kind can only start a chain. `undefined` - an unknown node - is not one. */
+export function isChainHeadKind(kind) {
+    return kind !== undefined && CHAIN_HEAD_KINDS.includes(kind);
+}
+export const workflowDocumentSchema = z.object({
+    schemaVersion: z.literal(WORKFLOW_DOCUMENT_SCHEMA_VERSION).optional(),
+    meta: z.object({
+        /**
+         * Deliberately not `.min(1)`. A user clearing the field to retype it would otherwise invalidate
+         * the document mid-keystroke and collapse the form around them — the exact defect step 1a shipped
+         * and had to fix. An empty name is recoverable; a missing one is still an error.
+         */
+        name: z.string(),
+        description: z.string().optional(),
+    }),
+    nodes: z.array(workflowNodeSchema).default([]),
+});
+/** Inspects the whole document. Execution must first restrict this to its selected reachable chain. */
+export function isInteractiveWorkflowDocument(document) {
+    return document.nodes.some((node) => node.kind !== "trigger" && node.interaction === "interactive");
+}
+export function validateWorkflowDocument(value) {
+    const result = workflowDocumentSchema.safeParse(value);
+    if (result.success) {
+        return { valid: true, document: result.data };
+    }
+    return {
+        valid: false,
+        errors: result.error.issues.map((issue) => ({
+            path: issue.path.length > 0 ? issue.path.join(".") : "document",
+            message: issue.message,
+        })),
+    };
+}
+/**
+ * Chain integrity, reported separately from schema validity and deliberately as warnings.
+ *
+ * A half-built workflow is a normal state to be in while authoring — a node whose `nextStep` is not
+ * written yet must not make the file invalid. Step 2's sync is where these become failures.
+ */
+export function validateWorkflowChain(nodes) {
+    const warnings = [];
+    // Not a chain-shape problem, but the same "authoring problem, not a schema violation" category:
+    // `agent` accepts "" so that adding a step or a reviewer never invalidates the document, and this
+    // is where that loosened value gets flagged instead.
+    for (const node of nodes) {
+        if (node.kind === "work" && node.agent === "") {
+            warnings.push({ nodeId: node.id, message: "This step has no agent assigned yet." });
+        }
+        if (node.kind === "review") {
+            if (node.interaction === "interactive" &&
+                node.reviewers.filter((r) => r.conversationRole === "workspace").length !== 1) {
+                warnings.push({
+                    nodeId: node.id,
+                    message: "An interactive review must designate exactly one workspace reviewer.",
+                });
+            }
+            for (const reviewer of node.reviewers) {
+                if (reviewer.agent === "") {
+                    warnings.push({ nodeId: node.id, message: "This step has a reviewer with no agent assigned yet." });
+                }
+            }
+        }
+    }
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const incoming = new Map();
+    const seen = new Set();
+    for (const node of nodes) {
+        if (node.nextStep === undefined) {
+            continue;
+        }
+        if (node.nextStep === node.id) {
+            warnings.push({ nodeId: node.id, message: "This step points at itself." });
+            seen.add(node.id);
+            continue;
+        }
+        const target = byId.get(node.nextStep);
+        if (target === undefined) {
+            warnings.push({ nodeId: node.id, message: `Next step "${node.nextStep}" is not a step in this workflow.` });
+            continue;
+        }
+        // A trigger is a chain head and nothing may point at one. Reported against the step holding the
+        // link rather than against the trigger, because the link is the thing that is wrong and the step
+        // holding it is the only one that can be repaired - the trigger itself is fine as it is.
+        if (isChainHeadKind(target.kind)) {
+            warnings.push({
+                nodeId: node.id,
+                message: "This step points at a trigger, and a trigger can only start a chain.",
+            });
+        }
+        incoming.set(node.nextStep, (incoming.get(node.nextStep) ?? 0) + 1);
+    }
+    for (const [nodeId, count] of incoming) {
+        if (count > 1) {
+            warnings.push({ nodeId, message: "More than one step leads here, and the flow is a single chain." });
+        }
+    }
+    // A cycle is only reachable once every hop resolves, so this runs after the checks above.
+    for (const node of nodes) {
+        if (seen.has(node.id)) {
+            continue;
+        }
+        const path = new Set();
+        let current = node;
+        while (current && !seen.has(current.id)) {
+            if (path.has(current.id)) {
+                warnings.push({ nodeId: current.id, message: "These steps form a cycle, so the run would never end." });
+                break;
+            }
+            path.add(current.id);
+            current = current.nextStep === undefined ? undefined : byId.get(current.nextStep);
+        }
+        for (const id of path) {
+            seen.add(id);
+        }
+    }
+    return warnings;
+}
+export function createDefaultWorkflowDocument(name) {
+    return {
+        schemaVersion: WORKFLOW_DOCUMENT_SCHEMA_VERSION,
+        meta: { name },
+        nodes: [
+            {
+                // A uuid, like every other node id. `id` is what becomes `WorkflowNodeRun.nodeKey` when a
+                // run is projected, and the editor's own `createNode` uses `crypto.randomUUID()` - so the
+                // literal "trigger" here meant every workflow ever created shipped with exactly one node
+                // whose key was not a uuid, and two workflows whose first steps collided on it.
+                id: crypto.randomUUID(),
+                kind: "trigger",
+                title: "Start",
+                source: "workspace-prompt",
+                position: { x: 0, y: 0 },
+            },
+        ],
+    };
+}
+/**
+ * Filename for a workflow, derived from its display name.
+ *
+ * Throws rather than returning a bare extension for a name with no ASCII alphanumerics, matching
+ * `CanvasManager.createCanvasFileName`. Step 1a's agent equivalent shipped without this guard and a
+ * non-Latin name silently wrote a dotfile.
+ */
+export function toSafeWorkflowFileName(name) {
+    const slug = name
+        .replace(/[^a-zA-Z0-9]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .toLowerCase();
+    if (!slug) {
+        throw new Error("Workflow name must contain at least one letter or number");
+    }
+    return `${slug}${WORKFLOW_FILE_EXTENSION}`;
+}
+//# sourceMappingURL=workflow-document.js.map

package/dist/workflow-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-document.js","sourceRoot":"","sources":["../src/workflow-document.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dazl/api-client",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "description": "Type-safe SDK for Dazl APIs, generated from OpenAPI specifications",
   "type": "module",
   "exports": {
@@ -11,6 +11,8 @@
     "./public/fetch-client": "./dist/public/client/index.js",
     "./db-types": "./dist/db/generated-types.js",
     "./feature-toggles-config": "./dist/feature-toggles-config.js",
+    "./agent-document": "./dist/agent-document.js",
+    "./workflow-document": "./dist/workflow-document.js",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -30,7 +32,8 @@
     "openapi"
   ],
   "peerDependencies": {
-    "kysely": ">=0.27.0"
+    "kysely": ">=0.27.0",
+    "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
     "kysely": {

package/src/agent-document.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+
+/** Bumped only on a breaking change to the document shape. */
+export const AGENT_DOCUMENT_SCHEMA_VERSION = "1";
+
+/** Directory the editor creates agent files in. Discovery is by extension, not by directory. */
+export const AGENTS_DIR = "agents";
+export const AGENT_FILE_EXTENSION = ".agent.json";
+
+/** The closed set of harnesses, matching dazl's harness-definitions.ts. */
+export const AGENT_HARNESSES = ["dazl", "claude", "codex", "grok", "opencode"] as const;
+export type AgentHarness = (typeof AGENT_HARNESSES)[number];
+
+/**
+ * One standing rule. `owners` are email addresses rather than dazl user ids, so the file stays
+ * readable in review and portable between workspaces; resolution to a user happens at sync time.
+ */
+export const agentRuleSchema = z.object({
+  text: z.string().min(1),
+  owners: z.array(z.string()).default([]),
+  blocking: z.boolean().default(false),
+});
+export type AgentRule = z.infer<typeof agentRuleSchema>;
+
+export const agentDocumentSchema = z.object({
+  schemaVersion: z.literal(AGENT_DOCUMENT_SCHEMA_VERSION).optional(),
+  meta: z.object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+  }),
+  systemPrompt: z.string(),
+  harness: z.enum(AGENT_HARNESSES),
+  model: z.string().optional(),
+  allowedMcpServers: z.array(z.string()).default([]),
+  rules: z.array(agentRuleSchema).default([]),
+});
+
+export type AgentDocument = z.infer<typeof agentDocumentSchema>;
+export type AgentDocumentInput = z.input<typeof agentDocumentSchema>;
+
+export interface AgentDocumentError {
+  /** Dotted path to the offending field, or "document" when the failure is at the root. */
+  path: string;
+  message: string;
+}
+
+export type AgentDocumentValidation =
+  { valid: true; document: AgentDocument } | { valid: false; errors: AgentDocumentError[] };
+
+export function validateAgentDocument(value: unknown): AgentDocumentValidation {
+  const result = agentDocumentSchema.safeParse(value);
+  if (result.success) {
+    return { valid: true, document: result.data };
+  }
+  return {
+    valid: false,
+    errors: result.error.issues.map((issue) => ({
+      path: issue.path.length > 0 ? issue.path.join(".") : "document",
+      message: issue.message,
+    })),
+  };
+}
+
+/**
+ * Every optional-with-a-default key is written out explicitly. The schema would fill them in on
+ * parse, but the file is also read by hand and by tools that do not run zod, so a freshly created
+ * agent states its own shape instead of relying on defaults being applied downstream.
+ */
+export function createDefaultAgentDocument(name: string): AgentDocumentInput {
+  return {
+    schemaVersion: AGENT_DOCUMENT_SCHEMA_VERSION,
+    meta: { name },
+    systemPrompt: "",
+    harness: "dazl",
+    allowedMcpServers: [],
+    rules: [],
+  };
+}
+
+/**
+ * Filename for an agent, derived from its display name. Mirrors `toSafeWorkflowFileName` so the
+ * two definition types name their files the same way.
+ *
+ * Throws for a name with no ASCII alphanumerics rather than returning a bare `.agent.json` dotfile
+ * that every such name would collide on.
+ */
+export function toSafeAgentFileName(name: string): string {
+  const slug = name
+    .replace(/[^a-zA-Z0-9]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60)
+    .toLowerCase();
+  if (!slug) {
+    throw new Error("Agent name must contain at least one letter or number");
+  }
+  return `${slug}${AGENT_FILE_EXTENSION}`;
+}