@shipfox/workflow-document 3.0.1 → 3.2.0

package/dist/document/workflow-document.js

@@ -52,6 +52,8 @@ export const WORKFLOW_DOCUMENT_JOB_OUTPUTS_MAX_ENTRIES = WORKFLOW_DOCUMENT_ENV_M
 export const WORKFLOW_DOCUMENT_STEP_OUTPUTS_MAX_ENTRIES = WORKFLOW_DOCUMENT_ENV_MAX_ENTRIES;
 export const WORKFLOW_DOCUMENT_STEP_OUTPUT_SCHEMA_MAX_SERIALIZED_BYTES = WORKFLOW_DOCUMENT_ENV_MAX_SERIALIZED_BYTES;
 export const WORKFLOW_DOCUMENT_STEP_OUTPUT_SCHEMA_MAX_DEPTH = 64;
+export const WORKFLOW_DOCUMENT_TOOL_WITH_MAX_SERIALIZED_BYTES = 32 * 1024;
+export const WORKFLOW_DOCUMENT_TOOL_WITH_MAX_DEPTH = 16;
 const utf8Encoder = new TextEncoder();
 export const workflowDocumentEnvSchema = z.record(envNameSchema, z.union([
     envStringValueSchema,
@@ -76,10 +78,186 @@ export const workflowDocumentEnvSchema = z.record(envNameSchema, z.union([
     description: `Environment variables as string, number, or boolean values. Each map allows up to ${WORKFLOW_DOCUMENT_ENV_MAX_ENTRIES} entries and ${WORKFLOW_DOCUMENT_ENV_MAX_SERIALIZED_BYTES} serialized bytes.`
 });
 const workflowDocumentStepOutputKeyPattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const workflowDocumentToolStepWithSchema = z// Validate nested values in an iterative refinement. A recursive Zod schema
+// would traverse hostile depth before the tool-input limits can reject it.
+.record(z.string().min(1), z.unknown()).superRefine((withValue, ctx)=>{
+    // The server injects `method` for `family.method` tools, so the author can
+    // never set it.
+    if ('method' in withValue) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [
+                'method'
+            ],
+            message: '`method` is not a valid tool input; the server injects it for `family.method` tools.'
+        });
+    }
+    validateWorkflowDocumentToolWith(withValue, ctx);
+}).transform((withValue)=>withValue).meta({
+    description: 'Tool inputs as a JSON tree. The map allows up to ' + WORKFLOW_DOCUMENT_TOOL_WITH_MAX_SERIALIZED_BYTES + ' serialized bytes and ' + WORKFLOW_DOCUMENT_TOOL_WITH_MAX_DEPTH + ' nesting levels. Tool steps are not available yet.'
+});
+function validateWorkflowDocumentToolWith(withValue, ctx) {
+    const activeObjects = new Set();
+    const tasks = [
+        {
+            kind: 'value',
+            value: withValue,
+            depth: 1,
+            path: []
+        }
+    ];
+    let serializedBytes = 0;
+    const addSerializedBytes = (byteLength)=>{
+        serializedBytes += byteLength;
+        if (serializedBytes <= WORKFLOW_DOCUMENT_TOOL_WITH_MAX_SERIALIZED_BYTES) return true;
+        ctx.addIssue({
+            code: 'custom',
+            message: `Tool \`with\` cannot serialize to more than ${WORKFLOW_DOCUMENT_TOOL_WITH_MAX_SERIALIZED_BYTES} bytes.`
+        });
+        return false;
+    };
+    while(tasks.length > 0){
+        const task = tasks.pop();
+        if (task === undefined) continue;
+        if (task.kind === 'bytes') {
+            if (!addSerializedBytes(task.byteLength)) return;
+            continue;
+        }
+        if (task.kind === 'end') {
+            activeObjects.delete(task.value);
+            if (!addSerializedBytes(task.byteLength)) return;
+            continue;
+        }
+        const { value, depth, path } = task;
+        if (value === null) {
+            if (!addSerializedBytes(4)) return;
+            continue;
+        }
+        if (typeof value === 'string' || typeof value === 'boolean') {
+            if (!addSerializedBytes(jsonPrimitiveByteLength(value))) return;
+            continue;
+        }
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path,
+                    message: 'Tool `with` values must be JSON-compatible.'
+                });
+                return;
+            }
+            if (!addSerializedBytes(jsonPrimitiveByteLength(value))) return;
+            continue;
+        }
+        if (typeof value !== 'object' || value === null) {
+            ctx.addIssue({
+                code: 'custom',
+                path,
+                message: 'Tool `with` values must be JSON-compatible.'
+            });
+            return;
+        }
+        if (depth > WORKFLOW_DOCUMENT_TOOL_WITH_MAX_DEPTH) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Tool \`with\` cannot be nested deeper than ${WORKFLOW_DOCUMENT_TOOL_WITH_MAX_DEPTH} levels.`
+            });
+            return;
+        }
+        if (activeObjects.has(value)) {
+            ctx.addIssue({
+                code: 'custom',
+                path,
+                message: 'Tool `with` values must be a JSON tree.'
+            });
+            return;
+        }
+        activeObjects.add(value);
+        if (Array.isArray(value)) {
+            if (!addSerializedBytes(1)) return;
+            tasks.push({
+                kind: 'end',
+                value,
+                byteLength: 1
+            });
+            for(let index = value.length - 1; index >= 0; index -= 1){
+                tasks.push({
+                    kind: 'value',
+                    value: value[index],
+                    depth: depth + 1,
+                    path: [
+                        ...path,
+                        index
+                    ]
+                });
+                if (index > 0) tasks.push({
+                    kind: 'bytes',
+                    byteLength: 1
+                });
+            }
+            continue;
+        }
+        if (!isJsonRecord(value)) {
+            ctx.addIssue({
+                code: 'custom',
+                path,
+                message: 'Tool `with` values must be a JSON tree.'
+            });
+            return;
+        }
+        if (!addSerializedBytes(1)) return;
+        tasks.push({
+            kind: 'end',
+            value,
+            byteLength: 1
+        });
+        const entries = Object.entries(value);
+        for(let index = entries.length - 1; index >= 0; index -= 1){
+            const entry = entries[index];
+            if (entry === undefined) continue;
+            const [key, child] = entry;
+            tasks.push({
+                kind: 'value',
+                value: child,
+                depth: depth + 1,
+                path: [
+                    ...path,
+                    key
+                ]
+            });
+            tasks.push({
+                kind: 'bytes',
+                byteLength: jsonPrimitiveByteLength(key) + 1
+            });
+            if (index > 0) tasks.push({
+                kind: 'bytes',
+                byteLength: 1
+            });
+        }
+    }
+}
+function jsonPrimitiveByteLength(value) {
+    return utf8Encoder.encode(JSON.stringify(value)).byteLength;
+}
+function jsonSerializedByteLength(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? undefined : utf8Encoder.encode(serialized).byteLength;
+    } catch  {
+        return undefined;
+    }
+}
+function isJsonRecord(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 const workflowDocumentStepOutputTypeSchema = z.enum(workflowDocumentStepOutputTypes).meta({
     description: 'Declared output type. Use `json` when the output has a JSON Schema.'
 });
-const workflowDocumentStepOutputDeclarationSchema = z.union([
+const workflowDocumentToolStepOutputMappingValueSchema = z.string().min(1).refine((value)=>value.includes('$' + '{{'), {
+    message: 'Tool-step output mappings must use a $' + '{{ }} expression.'
+});
+export const workflowDocumentStepOutputDeclarationSchema = z.union([
     workflowDocumentStepOutputTypeSchema.transform((type)=>({
             type
         })),
@@ -112,7 +290,17 @@ const workflowDocumentStepOutputDeclarationSchema = z.union([
         });
         return;
     }
-    const serializedBytes = utf8Encoder.encode(JSON.stringify(schema)).byteLength;
+    const serializedBytes = jsonSerializedByteLength(schema);
+    if (serializedBytes === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [
+                'schema'
+            ],
+            message: 'Schema must be a serializable JSON Schema document.'
+        });
+        return;
+    }
     if (serializedBytes > WORKFLOW_DOCUMENT_STEP_OUTPUT_SCHEMA_MAX_SERIALIZED_BYTES) {
         ctx.addIssue({
             code: 'custom',
@@ -133,7 +321,12 @@ const workflowDocumentStepOutputDeclarationSchema = z.union([
         });
     }
 });
-export const workflowDocumentStepOutputsSchema = z.record(z.string(), workflowDocumentStepOutputDeclarationSchema).superRefine((outputs, ctx)=>{
+function stepOutputsAreMappingForm(outputs) {
+    const interpolationOpen = '$' + '{{';
+    const values = Object.values(outputs);
+    return values.some((value)=>typeof value === 'string' && value.includes(interpolationOpen));
+}
+function stepOutputsRecordChecks(outputs, ctx) {
     const entries = Object.keys(outputs).length;
     if (entries > WORKFLOW_DOCUMENT_STEP_OUTPUTS_MAX_ENTRIES) {
         ctx.addIssue({
@@ -151,21 +344,38 @@ export const workflowDocumentStepOutputsSchema = z.record(z.string(), workflowDo
             message: 'Output keys must be CEL identifiers.'
         });
     }
-}).meta({
+}
+export const workflowDocumentStepOutputsSchema = z.record(z.string(), workflowDocumentStepOutputDeclarationSchema).superRefine((outputs, ctx)=>stepOutputsRecordChecks(outputs, ctx)).meta({
     description: `Named step outputs. Keys must be CEL identifiers and each step allows up to ${WORKFLOW_DOCUMENT_STEP_OUTPUTS_MAX_ENTRIES} declarations.`
 });
+// The tool-step `outputs` form maps output keys to a single `${{ }}` expression
+// over `result`. The expression layer validates the interpolation; the mapping
+// form is rejected with the reserved tool step fields until tool steps exist.
+export const workflowDocumentToolStepOutputsSchema = z.record(z.string(), workflowDocumentToolStepOutputMappingValueSchema).superRefine((outputs, ctx)=>stepOutputsRecordChecks(outputs, ctx)).meta({
+    description: 'Tool-step output mappings over `result`. Each value is exactly one $' + '{{ }} expression. Tool steps are not available yet.'
+});
+// `outputs` carries the declaration form on run, agent, and checkout steps and
+// the expression mapping form on tool steps. One value union accepts both so a
+// reserved tool step parses and is rejected by the step `superRefine`; zod
+// reports the declaration branch's own issues for malformed declarations, and
+// the step `superRefine` rejects the mapping form on every other step kind.
+const workflowDocumentStepOutputValueSchema = z.union([
+    workflowDocumentStepOutputDeclarationSchema,
+    workflowDocumentToolStepOutputMappingValueSchema
+]);
+const workflowDocumentStepOutputsFieldSchema = z.record(z.string(), workflowDocumentStepOutputValueSchema).superRefine((outputs, ctx)=>stepOutputsRecordChecks(outputs, ctx));
 const workflowDocumentTriggerBaseSchema = {
     source: z.string().min(1).meta({
-        description: 'Integration connection slug or built-in trigger source. See [Trigger sources](/reference/trigger-sources).'
+        description: 'Integration connection slug or built-in trigger source. See [Integrations](/integrations) for provider sources.'
     }),
     with: z.record(z.string(), z.unknown()).optional().meta({
-        description: 'Provider-specific values used to match or configure the trigger. See [Trigger sources](/reference/trigger-sources).'
+        description: 'Provider-specific values used to match or configure the trigger. See the provider event catalog in [Integrations](/integrations).'
     }),
     filter: z.string().min(1).optional().meta({
         description: 'CEL condition that filters matching events. It is not supported for `manual` or `cron` triggers. See [Expressions](/reference/expressions) and [Contexts](/reference/contexts#context-availability).'
     }),
     config: z.record(z.string(), z.unknown()).optional().meta({
-        description: 'Source-specific configuration. It is supported only for top-level triggers with a known built-in source. See [cron triggers](/reference/trigger-sources#cron).'
+        description: 'Source-specific configuration. It is supported only for top-level triggers with a known built-in source. See [Schedule workflows](/how-to/author-workflows/schedule-workflows).'
     })
 };
 export const triggerSourceConfigSchemas = {
@@ -181,8 +391,8 @@ export const triggerSourceConfigSchemas = {
 const triggerSourceConfigSchemaRegistry = triggerSourceConfigSchemas;
 export const workflowDocumentTriggerSchema = z.strictObject({
     ...workflowDocumentTriggerBaseSchema,
-    event: z.string().min(1).meta({
-        description: 'Provider event name that starts the workflow.'
+    event: z.string().min(1).optional().meta({
+        description: 'Event name that starts the workflow. Omit it to accept every event the source delivers. Sources that deliver one event, such as `manual`, `cron`, and custom webhooks, do not need it.'
     })
 }).superRefine((trigger, ctx)=>{
     if (trigger.config === undefined) return;
@@ -368,8 +578,11 @@ export const workflowDocumentAgentStepFields = [
 // payload keys are present and emits one targeted issue per failure mode (a
 // plain union would surface every branch's errors at once). The `agent`
 // keyword is declared only so the reserved-keyword case produces a clear
-// message instead of a generic "unrecognized key".
-export const workflowDocumentStepSchema = z.strictObject({
+// message instead of a generic "unrecognized key". The `tool`, `connection`,
+// `with`, and tool-step `outputs` mapping form are declared the same way: they
+// parse so their shape is checked, then any step carrying a reserved tool field
+// is rejected until the tool step kind exists.
+const workflowDocumentStepBaseSchema = z.strictObject({
     key: z.string().min(1).optional().meta({
         description: 'Stable step key for dependencies and outputs.'
     }),
@@ -410,16 +623,24 @@ export const workflowDocumentStepSchema = z.strictObject({
     agent: z.unknown().optional().meta({
         description: 'Reserved keyword. It is rejected; use `prompt` to define an agent step.'
     }),
+    tool: z.string().min(1).optional().meta({
+        description: 'Literal integration tool id for a tool step. It is rejected; tool steps are not available yet.'
+    }),
+    connection: z.string().min(1).optional().meta({
+        description: 'Literal integration connection slug for a tool step. It is rejected; tool steps are not available yet.'
+    }),
+    with: workflowDocumentToolStepWithSchema.optional(),
     gate: workflowDocumentStepGateSchema.optional().meta({
         description: 'Success gate and optional restart behavior after the step runs.'
     }),
     env: workflowDocumentEnvSchema.optional().meta({
         description: 'Environment variables for a run step. They are not valid on an agent step.'
     }),
-    outputs: workflowDocumentStepOutputsSchema.optional().meta({
-        description: 'Named output declarations produced by this step.'
+    outputs: workflowDocumentStepOutputsFieldSchema.optional().meta({
+        description: 'Named output declarations produced by this step, or on a tool step a mapping of output keys to exactly one $' + '{{ }} expression over `result`. Tool steps are not available yet.'
     })
-}).superRefine((step, ctx)=>{
+});
+export const workflowDocumentStepSchema = workflowDocumentStepBaseSchema.superRefine((step, ctx)=>{
     if (step.agent !== undefined) {
         ctx.addIssue({
             code: 'custom',
@@ -430,6 +651,26 @@ export const workflowDocumentStepSchema = z.strictObject({
         });
         return;
     }
+    const reservedToolField = step.tool !== undefined ? 'tool' : step.connection !== undefined ? 'connection' : undefined;
+    if (reservedToolField !== undefined || step.with !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [
+                reservedToolField ?? 'with'
+            ],
+            message: 'Tool steps are not available yet.'
+        });
+        return;
+    }
+    if (step.outputs !== undefined && stepOutputsAreMappingForm(step.outputs)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [
+                'outputs'
+            ],
+            message: 'The `outputs` mapping form is reserved for tool steps.'
+        });
+    }
     if (step.checkout !== undefined) {
         if (step.run !== undefined) {
             ctx.addIssue({
@@ -502,7 +743,10 @@ export const workflowDocumentStepSchema = z.strictObject({
             message: 'An agent step requires "prompt".'
         });
     }
-});
+}).transform(({ outputs, ...step })=>outputs === undefined ? step : {
+        ...step,
+        outputs: outputs
+    });
 const workflowDocumentJobOutputsSchema = nonEmptyRecordSchema(z.string().min(1)).superRefine((outputs, ctx)=>{
     const entries = Object.keys(outputs).length;
     if (entries > WORKFLOW_DOCUMENT_JOB_OUTPUTS_MAX_ENTRIES) {
@@ -565,14 +809,41 @@ export const workflowDocumentSchema = z.strictObject({
     })
 });
 function maxJsonDepth(value) {
-    if (value === null || typeof value !== 'object') return 0;
-    if (Array.isArray(value)) {
-        if (value.length === 0) return 1;
-        return 1 + Math.max(...value.map(maxJsonDepth));
+    let maximumDepth = 0;
+    const activeObjects = new Set();
+    const pending = [
+        {
+            kind: 'enter',
+            value,
+            depth: 0
+        }
+    ];
+    while(pending.length > 0){
+        const current = pending.pop();
+        if (current === undefined) continue;
+        if (current.kind === 'leave') {
+            activeObjects.delete(current.value);
+            continue;
+        }
+        if (current.value === null || typeof current.value !== 'object') continue;
+        if (activeObjects.has(current.value)) continue;
+        activeObjects.add(current.value);
+        const depth = current.depth + 1;
+        maximumDepth = Math.max(maximumDepth, depth);
+        pending.push({
+            kind: 'leave',
+            value: current.value
+        });
+        const children = Object.values(current.value);
+        for(let index = children.length - 1; index >= 0; index -= 1){
+            pending.push({
+                kind: 'enter',
+                value: children[index],
+                depth
+            });
+        }
     }
-    const entries = Object.values(value);
-    if (entries.length === 0) return 1;
-    return 1 + Math.max(...entries.map(maxJsonDepth));
+    return maximumDepth;
 }
 function isJsonSchemaDocument(value) {
     return typeof value === 'boolean' || typeof value === 'object' && value !== null && !Array.isArray(value);