Process Flows

A Process Flow is a structured, repeatable workflow with stages, tasks, and personas — kickoffs, audits, onboarding, due-diligence reviews. You author it once as a Process Flow using this SDK and ship it inside a .scrydon-extension.tar.gz; the platform instantiates it per run as a Process Flow.

Install

bun add -d @scrydon/sdk-authoring zod

import {
  defineProcessFlow,
  defineStage,
  defineTask,
  defineAction,
  definePersona,
  defineVoiceTrigger,
} from '@scrydon/sdk-authoring/process-flows'

Anatomy of a template

A complete example

import {
  defineProcessFlow,
  defineStage,
  defineTask,
  defineAction,
  definePersona,
} from '@scrydon/sdk-authoring/process-flows'

export default defineProcessFlow({
  manifestVersion: 1,
  package: {
    id: 'acme.kickoff',
    name: 'Acme Customer Kickoff',
    version: '1.0.0',
  },
  template: {
    slug: 'acme-kickoff',
    name: 'Customer Kickoff',
    description: 'Standard onboarding flow for new enterprise customers',
    version: '1.0.0',
    defaultView: 'wizard',
    executionConfig: {
      stageFlow: 'sequential',
      taskFlow: 'parallel',
      allowRuntimeTaskCreation: true,
    },
    metadata: {
      icon: 'rocket',
      color: '#2563eb',
      tags: ['onboarding', 'sales'],
    },
    personas: [
      definePersona({ slug: 'csm', displayName: 'Customer Success Manager', cardinality: 'one' }),
      definePersona({ slug: 'champion', displayName: 'Customer Champion', cardinality: 'one' }),
      definePersona({ slug: 'system', displayName: 'System', cardinality: 'system' }),
    ],
    stages: [
      defineStage({
        slug: 'discovery',
        name: 'Discovery',
        transitionMode: 'manual',
        estimatedDuration: { value: 5, unit: 'days' },
      }),
      defineStage({
        slug: 'rollout',
        name: 'Rollout',
        transitionMode: 'approval',
      }),
    ],
    taskTemplates: [
      defineTask({
        slug: 'collect-stakeholders',
        stageSlug: 'discovery',
        name: 'Collect stakeholders',
        defaultAssignedRoleSlug: 'csm',
        actions: [
          defineAction({
            name: 'Stakeholder list',
            actionType: 'document',
            isRequired: true,
            metadata: { persona: 'csm' },
          }),
        ],
      }),
      defineTask({
        slug: 'kickoff-call',
        stageSlug: 'discovery',
        name: 'Kickoff call',
        dependsOnTaskSlugs: ['collect-stakeholders'],
        actions: [
          defineAction({
            name: 'Record kickoff call',
            actionType: 'voice_trigger',
            isRequired: true,
            metadata: { triggerPath: '/kickoff/' },
          }),
          defineAction({
            name: 'Capture summary to KB',
            actionType: 'workflow',
            isRequired: false,
            workflowId: 'system.summarize-meeting',
            metadata: { promoteToCorpus: 'summary' },
          }),
        ],
      }),
      defineTask({
        slug: 'rollout-plan',
        stageSlug: 'rollout',
        name: 'Approve rollout plan',
        dependsOnTaskSlugs: ['kickoff-call'],
        actions: [
          defineAction({
            name: 'Approve plan',
            actionType: 'approval',
            isRequired: true,
            metadata: { persona: 'champion' },
          }),
        ],
      }),
    ],
    voiceTriggers: [],
  },
})

Action Types

See Action Types for a per-type deep-dive with copy-pasteable examples, runtime UX notes, and the metadata fields each type reads.

Approval-gate routing

When a stage has transitionMode: "approval", the platform notifies the right people the moment a task reaches the gate. Three fields on defineStage control who is notified and how many approvals are required:

When the gate is reached, the platform sends a process.approval_requested notification to each resolved user and displays "Approval request sent · N notified · sent <date>" in the approval task sheet.

Example — legal-quorum gate:

defineStage({
  slug: 'legal-review',
  name: 'Legal review',
  transitionMode: 'approval',
  approverPersona: 'legal-reviewer',
  resolutionMode: 'quorum',
  quorumN: 2,
})

The flow halts at the gate until the quorum is satisfied. Rejecting the gate halts the flow regardless of quorum count — a single rejection is always final.

Grounding an AI step in workspace documents (metadata.retrieval)

The reverse direction: a workflow action that runs an agent — a @system/* built-in or an extension/canvas workflow (inline or sibling) — can be grounded in one or more documents uploaded earlier in the flow, so the agent reasons over real inputs instead of the task name alone. Declare it with metadata.retrieval on the action:

defineAction({
  name: "AI Qualification Assessment",
  actionType: "workflow",
  isRequired: false,
  executionMode: "automatic",          // run when the stage is entered
  workflowId: "@system/agent-project-qualifier",
  metadata: {
    aiAgent: "project-qualifier",
    // Where the agent result lands, by target ACTION TYPE (see below):
    // an assessment on this workflow step itself, and an advisory banner
    // on the flow's human approval action.
    outputSurface: [
      {
        kind: "workflow",
        contentType: "project_qualification_assessment",
        pageTitle: "AI Qualification Assessment",
      },
      {
        kind: "approval",
        targetTaskSlug: "go-no-go-decision",
        advisorySource: "ai-qualification",
      },
    ],
    retrieval: {
      // The document(s) the agent must judge. `fromTask` is the slug of an
      // earlier task: its completed document action's page, its file_upload
      // action's ingested documents, and/or its workflow (agent) action's
      // assessment page are resolved as stable, source-level entries.
      inputs: [{ fromTask: "upload-source", mode: "full" }],
      // Optional per-source maximum. The exact shared rendered-block budget
      // can assign less after headings, status text, and markers are counted.
      // Omitted → mode-derived default (full: 24,000; summary: 4,000).
      inputDocMaxChars: 60_000,
    },
  },
})

The Prompt & Context panel reports one row for every stable known source, including same-title siblings. It distinguishes represented, omitted for capacity, read failed, and summary fallback outcomes; only content-bearing sources contribute output references. Preparation is bounded to 500 inventoried sources, 1 MB per loaded body, 8 MB across all declared inputs, 24 summary calls at concurrency 6, and 60 seconds. If the authorized inventory cannot be completed within its source or elapsed-time bound, preparation stops with a generic error before the agent model runs. Once inventory is complete, a summary deadline uses the visibly marked source-local fallback described above.

Today workflow (assessment on the step) and approval (advisory on a target approval action) are the implemented output surfaces. The retrieval spec itself is generic and works for any agent-bearing workflow step that needs grounding — @system/* built-ins receive the gathered context as their user message automatically, while extension/canvas workflows must additionally reference <start.processFlowContext> in a block to receive it (see Receiving process-flow context — without the reference the gathered context is dropped).

One knowledge base for every run (knowledge.scope)

By default each run of a process flow gets its own knowledge base. Set knowledge.scope: "template" and every run of that flow in a workspace environment writes into one shared knowledge base instead:

template: {
  // …
  knowledge: { scope: "template" },
}

• The shared base is created the first time the flow runs in an environment and appears in the workspace's knowledge-base list, badged Process flow.
• Each run owns one folder, instances/<date>-<run name>-<id>/, holding its uploads, documents, transcripts and closing summary. AI steps read their own run's folder plus anything outside instances/ — so reference material members upload at the root of the base is available to every run.
• Earlier completed runs ground later ones through their own folders.
• Deleting a run removes only its folder; deleting the base from the knowledge page is allowed and the next run provisions a fresh one.
• Runs that started before the flow declared template keep their own base.

If your workflows address the base directly. A canvas step that reads <start.processFlow.knowledgeBaseId> gets the shared base under scope: "template", and the Knowledge block and knowledge tool have no folder narrowing of their own yet — such a step sees every run's folder, not just its own. Prefer the declared-input grounding (metadata.retrieval), which is folder-scoped for you. The run's own folder path is exposed as <start.processFlow.knowledgeBaseFolder> — the value is instances/<date>-<run name>-<id>, i.e. the folderPath every page of the run lives at or under, so it can be pasted into a folder scope as-is.

scope: "instance" (the default) keeps today's behaviour.

Carry earlier runs forward (knowledge.priorCycles)

A new run can build on what earlier runs of the same flow decided. By default it carries over the five most recent completed runs in the same workspace environment:

• its AI steps receive relevant excerpts from those runs, and
• its steps' shared conversations receive each run's closing summary and can search those runs' pages, so a question such as "what did we decide last time?" is answered from — and cites — the earlier runs.

Set the number per flow:

template: {
  // …
  knowledge: {
    scope: "template",
    priorCycles: { maxCycles: 3 },
  },
}

• maxCycles is an integer from 0 to 10; 0 turns carry-over off.
• Leave priorCycles out to follow the platform default (currently 5).
• The value is frozen into each run when it starts, so publishing a new version of the extension does not change a run that is already in progress.
• A single AI step can still override it with metadata.priorCycles.maxCycles, or opt out entirely with excludeContext: ["priorCycles"].
• Works with either scope. Runs still in progress, cancelled runs, and pages classified above the reader's clearance are never carried over.

Task DAG validation

Tasks can declare:

• dependsOnTaskSlugs — other tasks that must complete first
• unlockAfterTaskSlug + unlockDelay — a soft gate that opens N days/weeks after a predecessor finishes

The inspect CLI runs DFS cycle detection (WHITE/GRAY/BLACK) and fails closed on any cycle. Stable error codes:

Build, inspect, upload

bunx @scrydon/sdk-authoring extension validate src/extension.ts

bunx @scrydon/sdk-authoring extension build src/extension.ts --outDir dist
# → dist/<package.id>-<package.version>.scrydon-extension.tar.gz

bunx @scrydon/sdk-authoring extension inspect dist/acme-kickoff-1.0.0.scrydon-extension.tar.gz

curl -X POST "$AGENTIC_URL/api/extensions/import?organizationId=$ORG_ID&workspaceEnvironmentId=$ENV_ID" \
  -H "Cookie: $SESSION_COOKIE" \
  -F "file=@dist/acme-kickoff-1.0.0.scrydon-extension.tar.gz"

Extension layout

<extension>.scrydon-extension.tar.gz
├── extension.json                          # top-level extension manifest (ExtensionArchiveManifestSchema)
├── ontology/
│   └── manifest.json                  # OntologyManifestSchema — may be empty for flow-only extensions
├── workflow-<slug>/                   # optional — zero or more workflow subdirs
│   └── manifest.json                  # WorkflowManifestSchema
└── process-flow/
    ├── manifest.json                  # ProcessFlowManifestSchema
    ├── assets/                        # optional — JSON / image assets referenced by the flow
    │   ├── icon.svg
    │   └── preview.png
    └── meta/                          # optional — non-functional metadata (e.g. sbom.cdx.json)

Each subdir round-trips as a valid standalone artifact. Allowed asset extensions: .json, .svg, .png, .jpg, .jpeg, .gif, .md. Symlinks, hardlinks, absolute paths, and path traversal (..) are rejected by the inspector.

When an extension ships workflows, the importer runs them in their own phase before process-flow install — that way every workflowSlug on an action template resolves to a materialized workflowId before the process flow lands in the database. See Workflows for the slug-rebind contract.

Security caps

The runtime inspector reads the archive in streaming mode (tar.list parser-only — never extracts to disk) and enforces hard caps:

The /import route returns 413 for size violations and 400 for structure or graph violations.

Why no executable code

process flows are declarative. Custom logic is referenced — by workflowId (a workflow already living in the tenant) or by workflowSlug (a workflow shipped alongside the template in the same Extension) — not archived. Even when a Extension ships workflows in workflow-<slug>/ subdirs, the on-disk representation is pure JSON; the runtime block catalog lives in the platform. This keeps the surface deterministic, reproducible, and uploadable by non-engineering authors.

Where to next