Workflow Code

Code-first authoring API and routed tela workflow command implementation for Tela Workflow V3.

Workflow Code lets you define Tela workflows in TypeScript, keep them in source control, validate them locally or in CI, and sync/publish reviewed workflow versions to Tela.

Install

pnpm add @meistrari/workflow-code

The package provides:

• library import: @meistrari/workflow-code
• CLI command group: tela workflow

There is no standalone workflow-code binary; all commands route through @meistrari/tela-cli.

Current MVP status: routed init, create, compile, docs, codegen, sync, publish, and watch behavior exists. tela workflow init is the local project scaffold for Workflow Code: it creates safe starter files/scripts and never contacts Tela APIs. tela workflow create <target> is the explicit remote provisioning command: it creates the remote workflow first, binds returned identities in config, generates local template files, then syncs when possible. tela workflow compile [target] loads Workflow Code config, selects a workflow target by the config workflows map key, evaluates the target entrypoint, and emits an inspectable compiled Workflow V3 payload. It is non-mutating: it does not call Tela APIs, write state, or publish versions. tela workflow codegen refreshes or reuses the active-context workspace catalog and writes shared remote() TypeScript metadata. tela workflow sync [target] compiles and consolidates the requested target, or all configured workflow prompts when no target is provided. tela workflow publish [target] publishes exact versions proven to match local compiled source, for all configured targets by default or one positional target. tela workflow watch [target] runs an initial codegen/sync cycle, then serializes debounced source, config, and Tela Local context changes into follow-up sync cycles.

Quick start

Initialize a Workflow Code project scaffold:

tela workflow init

Init creates workflow-code.config.ts, .env.example, a missing tsconfig.json, a .gitignore entry for dev-context lockfiles, adds @meistrari/workflow-code to devDependencies, and adds missing package.json scripts such as workflow:compile, workflow:codegen, workflow:sync, workflow:publish, workflow:run, and workflow:watch. Existing files and scripts are not overwritten by default; skipped or conflicting scaffold pieces are reported as structured diagnostics.

Pass repeatable --workflow <workflow-key> flags to scaffold workflow targets and source files:

tela workflow init --directory ./workflow-app --workflow invoice-processing --workflow review

Without workflow keys, init writes workflows: {} and does not create dangling source files or example targets. Init is interactive by default for target directory, workflow keys, git initialization, and dependency installation. The workflow-key prompt is the interactive abstraction of repeatable --workflow <workflow-key> flags and defaults to no keys; the git and dependency prompts default to no. Use --yes for non-interactive safe defaults: current directory, no workflow keys, no git init, and no dependency install. Use --workflow, --init-git / --no-init-git, --install-deps / --no-install-deps, and --package-manager bun|pnpm|npm|yarn to choose explicitly. When dependency installation is enabled and package.json is missing, init first runs the selected package manager's non-interactive init command, then merges Workflow Code scripts.

Workflow Code loads .env files before evaluating the TypeScript config. Use --env <path> to provide a custom dotenv file for a command.

A generated --workflow document-research source starts minimal:

import { build, workflow } from '@meistrari/workflow-code'

const workflowKey = workflow('document-research')

export default build(workflowKey, {
    input: [],
    nodes: [],
})

Add MVP factories such as input, llm, published-Agent agent(remoteRef, options), canvas(remoteRef, options), template(remoteRef, options), code, splitter, crop, map, and condition, plus vault.ref() for existing Vault files, as your workflow grows.

Compile the selected workflow source locally:

tela workflow compile

tela workflow compile [target] loads Workflow Code config, selects a workflow target by the config workflows map key, evaluates the target entrypoint, and emits an inspectable compiled Workflow V3 payload. It is non-mutating and offline: it does not require or validate remote projectId/promptId, call Tela APIs, write state, or publish versions. Keep using this positional compile selector.

In this release, compile auto-selects the only configured workflow. When multiple workflows are configured, pass positional target to choose one for compile. sync, publish, and watch keep the same positional target selector; when omitted, they operate on all configured workflows. run requires that positional target:

tela workflow sync
tela workflow sync invoice-processing
tela workflow publish invoice-processing
tela workflow watch
tela workflow watch invoice-processing
tela workflow run invoice-processing

create, sync, publish, and watch are implemented remote commands. Run remains unavailable in this release.

Sync

tela workflow sync [target] compiles Workflow Code targets and writes them to configured Tela prompts through the prompt-version lifecycle API. With target, sync runs only that configured workflow. Without target, sync runs every configured workflow. Sync requires an existing promptId in each active context binding or legacy target config.

Sync does not publish. Before any selected workflow is mutated, it validates every direct Vault ref carried by the compiled targets. It then creates or replays a consolidated prompt version through POST /prompt-version/:id/edit, verifies the exact returned version with GET /prompt-version/:id, and records the result in .tela/workflows/<workflowKey>/contexts/<context>/lock.json.

If the remote prompt version changed since the last successful sync, the CLI asks:

Remote changed since last sync. Last sync version: v3 / Current version: v5. Continue and consolidate new version v6?

Pass --yes to continue non-interactively. Without --yes in a non-interactive environment, sync fails before mutation.

Authoring model

A workflow source file exports one built declaration:

export default build(invoiceWorkflow, {
    inputs: [document],
    nodes: [extract, research],
})

Workflow Code infers graph topology from ordered node arrays. You do not author raw Workflow V3 edge objects, endpoint pairs, edge IDs, or ports.

Rules:

• adjacent top-level llm(), published-Agent, Canvas/Workflow, Template, code(), splitter(), crop(), docTemplate(), map(), and condition() nodes run sequentially in the MVP
• map bodies lower recursively through subgraph-root and body-local default edges
• condition cases lower through deterministic branch ports and converge non-empty or empty branch tails into the next containing node
• a final direct stop() in a condition case/default branch terminates only that branch and never converges to the next containing node

Inputs

const topic = input.text({ name: 'topic', required: true })

const document = input.file({
    name: 'document',
    required: true,
})

Workflow input references compile to stable Workflow V3 input URI references. Run inputs use the author-facing input names you declared in source.

Modules

Implemented MVP Workflow Code module factories:

• llm()
• agent(remoteRef, options)
• canvas(remoteRef, options)
• template(remoteRef, options)
• code()
• splitter()
• crop()
• docTemplate()
• map() for ordered nested bodies
• condition() for synchronous predicate branches
• stop() for terminal condition branches

Planned module factories outside the implemented MVP subset:

Implemented module factories return typed node handles that can be placed in top-level nodes arrays and referenced by later modules. code() nodes capture a TypeScript handler for later Workflow runtime execution: local compile evaluates trusted declaration files, but does not call the handler. Instead, compile extracts supported handler source and source-visible closure dependencies, preserves supported package imports, merges default/inferred/user libraries, and emits generated code for the sandbox. Keep extracted handler/helper/type names away from generated runtime names such as execute, __workflowFn, and TelaInput; those names are reserved inside the generated code bundle.

Templates

Generate the active workspace catalog, then select a Template by its generated path or explicit ID:

const starter = remote().template().Global['Invoice Starter']

const rendered = template(starter, {
    name: 'Render invoice',
    input: {
        variables: ({ ref }) => ({ document: ref(document).formats().multimodal }),
        tags: ['invoice'],
    },
})

Generated Template refs type required/optional variables and the node output. Offline compile keeps the ref symbolic; sync validates it against a fresh catalog, locks the stable Template ID/version and input/output contract, and lowers the call to Workflow V3 template input fields.

Document templates

docTemplate() lowers to the Workflow V3 document-templater action. Its input.template accepts a .docx vault.ref(), vault.asset(), or callback reference to a text workflow input/string-compatible earlier-node field. input.placeholders is a keyed record of literal strings, Vault refs/assets, text workflow inputs, or string-compatible earlier-node fields; outputFilename names the generated document.

const rendered = docTemplate({
    name: 'Render invoice',
    input: {
        template: ({ ref, paths }) => ref(selectTemplate, paths(selectTemplate).vaultUrl),
        outputFilename: 'invoice.docx',
        placeholders: ({ ref, paths }) => ({
            customer: ref(customerName),
            total: ref(extract, paths(extract).total),
        }),
    },
})

References

Reference-capable fields receive target-scoped helpers:

const summarize = llm({
    name: 'Summarize invoice',
    input: {
        prompt: ({ ref, paths }) =>
            `Summarize ${ref(extract, paths(extract).invoiceNumber)}`,
    },
})

Use supported MVP refs with input and previous-node handles instead of raw IDs or hand-written URI strings. Supported forms are ref(input), ref(previousNode), ref(previousNode, paths(previousNode).field), and field-compatible format keys from Tela's English labels, such as .formats().parser, .formats().multimodal, or .formats().string.

Splitter, Crop, and Vault refs

const existing = vault.ref('vault://550e8400-e29b-41d4-a716-446655440000')

const pages = splitter({
    name: 'Split document pages',
    input: {
        file: ({ ref }) => ref(document),
        mode: 'single-pages',
    },
})

const existingPages = splitter({
    name: 'Split existing document',
    input: {
        file: existing,
        mode: 'smart-files',
        customPrompt: 'Separate invoices from receipts.',
        customPromptMode: 'fallback',
    },
})

const selectedPages = crop({
    name: 'Crop selected pages',
    input: {
        file: ({ ref }) => ref(document),
        indexes: [1, '3-5'],
    },
})

splitter.input.file and crop.input.file are exclusive file fields: they accept a compatible workflow input/previous-node ref, one vault.ref(), or an array of Vault refs. Direct Vault refs lower to runtime transport-file objects with both fileUrl and vaultReference; input and step refs remain Workflow V3 URI strings. crop.input.indexes accepts integer page indexes and string ranges such as '3-5'; its PDF type defaults to 'pdf'. vault.ref() is inert during source evaluation and does not need a lockfile entry, but sync/publish validate access in the active Tela context.

Compatible previous-node refs include declared file schemas from llm(), known splitter()/crop() file paths, and statically inferred code() returns. Code handlers may return transport-file objects, file arrays, nested file paths, or File/Blob values that the Workflow runtime uploads to Vault. Compile does not call the handler and rejects scalar, malformed, any, unknown, or mixed file/non-file returns before lowering either document action's file field.

Map example

const pages = splitter({
    name: 'Split document pages',
    input: { file: ({ ref }) => ref(document) },
})

const extractPage = llm({
    name: 'Extract page data',
    input: { prompt: 'Extract line items from the current map item.' },
})

const loopPages = map({
    name: 'Loop pages',
    input: {
        over: ({ ref }) => ref(pages),
        mapVariable: 'page',
    },
    nodes: [extractPage],
})

Condition example

const route = condition({
    cases: {
        approved: {
            when: ({ ref, paths }) => ref(extract, paths(extract).total) < 10_000,
            nodes: [autoApprove],
        },
    },
    default: { nodes: [requestReview] },
})

export default build(invoiceWorkflow, {
    inputs: [document],
    nodes: [extract, route, notifyRequester],
})

notifyRequester runs after normal and empty branches. Predicate handlers must be synchronous and return boolean. Put stop() only as the final direct node of a condition branch when that branch should terminate without converging to the next node; root, map-body, nested-non-direct, and non-final placements report compiler.stop.invalid_placement.

CLI commands

Target command surface:

tela workflow init [--directory path] [--config path] [--workflow key...] [--yes] [--init-git|--no-init-git] [--install-deps|--no-install-deps] [--package-manager bun|pnpm|npm|yarn]
tela workflow create <target> [--project project-id] [--config path] [--env path] [--json]
tela workflow codegen [--json]
tela workflow compile [target] [--config path] [--env path] [--json]
tela workflow sync [target] [--config path] [--env path] [--yes] [--json]
tela workflow publish [target] [--environment name] [--create-environment-if-missing] [--config path] [--env path] [--yes] [--json]
tela workflow run <target> --input name=value [--env path] [--follow]
tela workflow watch [target] [--config path] [--env path] [--json]

init

Scaffolds a local Workflow Code project. Init creates the target directory when it does not exist; --directory <path> selects it and defaults to .. Init creates workflow-code.config.ts, .env.example, a missing tsconfig.json, a .gitignore entry for .tela/workflows/*/contexts/dev/lock.json, adds @meistrari/workflow-code to devDependencies, and adds missing package.json Workflow Code scripts inside that directory. Generated config references ./tsconfig.json, uses outDir: '.tela/workflows', and writes workflows: {} unless one or more --workflow <workflow-key> flags are passed or interactive workflow keys are entered.

Each --workflow <workflow-key> adds a config target and src/workflows/<workflow-key>.workflow.ts source file. Generated workflow source imports only from @meistrari/workflow-code, declares const workflowKey = workflow('<workflow-key>'), and default exports build(workflowKey, { input: [], nodes: [] }).

Init is interactive by default for target directory, workflow keys, git initialization, and dependency installation when a terminal prompt is available; the directory prompt runs first and defaults to ., then the workflow-key prompt accepts comma- or space-separated keys and defaults to none. The git and dependency prompts default to no. --yes runs non-interactively with safe defaults: current directory, no workflow keys, no git initialization, and no dependency installation. Use --directory <path>, repeatable --workflow <key>, --init-git / --no-init-git, --install-deps / --no-install-deps, and --package-manager bun|pnpm|npm|yarn to choose explicitly; Bun is the default package manager when installation is requested. If installation is enabled and package.json is missing, init runs the selected package manager's non-interactive init command before dependency installation.

Init never contacts Tela APIs, creates remote resources, writes lockfiles, creates generated artifacts, prints env values, or uses Workflow Code-specific auth/token storage. Existing config, workflow source, env files, tsconfig.json, .gitignore content, and package scripts are not overwritten by default; init reports skipped/conflicting paths and scripts and continues creating other non-conflicting pieces where safe. --json reports diagnostics plus written and skipped paths.

create

Creates a new remote Tela workflow, records the returned remote identity in workflow-code.config.ts, scaffolds template directories/source files for the new workflow target, and syncs when possible.

Create uses shared Tela Local credentials and the active context. It takes projectId from the target's active context binding (or a legacy top-level binding when no contexts map exists). Pass --project <project-id> when creating a new target or adding a missing active binding; project selection is never inferred from another workflow or merely from the active workspace. If the active target already has a promptId, create fails before contacting the remote API and points to sync.

Order:

1. Create workflow remotely in the selected Tela project/context.
2. Add the remote identity data to workflow-code.config.ts under the new workflows[target] entry.
3. Generate template directories and source files for the new workflow.
4. If compile/sync preconditions are available, run sync so the remote workflow has a version matching local source.

Create is explicit remote provisioning and does not run as part of init. It preserves existing files/config entries by default, reports conflicts as diagnostics, and does not publish by default.

The remote request includes a stable idempotency key for the same canonical config/target/context/workspace/project tuple, so paths that reach the same config through symlinked parent directories share one remote creation identity and one local write lock. Immediately before the POST, create reloads the selected source and transitive local imports, reapplies the prepared remote-reference snapshot, and requires unchanged source/compiled hashes. The successful response must contain non-empty prompt and bootstrap-version ids plus non-empty project and workspace ids matching the request before create writes local bindings. Create does not issue follow-up prompt/version reads; complete representation validation is deferred until the create endpoint returns those fields. If the response contains a valid prompt id but omits or malforms the bootstrap version identity, create stops before local writes/sync and preserves the prompt id and create idempotency key in human/JSON recovery output (bootstrapVersionId is null). If the POST result is unknown, the same output preserves the attempted idempotency key and reports promptId: null when Tela returned no trustworthy identity.

After remote creation, config updates are serialized with an exclusive per-config lock, hash-checked immediately before atomic replacement, and reloaded through the normal loader. Ambiguous mutation-path config syntax is rejected before POST, and the reloaded effective entry/workflow key/context/project/prompt binding must match the create plan before sync. Source is created with exclusive-write semantics. An existing source is reported as preserved only after a second existence check; if it was deleted after preflight, create returns a recoverable conflict instead of recreating it with a different starter or reporting it as skipped. Recovery actions follow the completed local phase: only a failed config write asks for a manual binding, a failed source write keeps the completed binding and describes source repair, and reload/effective-binding failures keep both config/source work and describe the specific repair. The best-effort follow-up sync keeps the provisioning context/workspace/project/prompt/bootstrap identity pinned. If the remote advances beyond that bootstrap first, automatic sync is skipped before edit. Other failures in preflight are reported as a skipped follow-up with warnings, while failures after mutation_attempted preserve error diagnostics, return a non-zero exit code, and expose the pending-sync lockfile, idempotency key, and target version for recovery. If a local write fails, output still includes prompt id, bootstrap version id, project/workspace/context, idempotency key, and written/skipped paths for recovery. --json reports the sync status and phase and always reports published: false.

codegen

Generates shared TypeScript authoring support. Codegen is workspace-scoped and accepts no positional target: it resolves the active Tela Local context/workspace, refreshes the authenticated catalog when possible, and writes .tela/workflow-code/generated/workflow-code.generated.d.ts plus .tela/workflow-code/catalogs/{workspaceId}/remote-catalog.snapshot.json. If refresh fails, codegen may reuse only a complete cached snapshot for the same active context and workspace and reports the snapshot timestamp.

Generated metadata exposes remote() catalogs for canvases, workflows, templates, published Agents, and LLM models. Generated name paths are locked to stable remote IDs/refs so sync/codegen can warn on title changes and fail rather than silently rebinding a path to a different resource. Vault helpers are independent: vault.asset() declares local upload dependencies for sync, while vault.ref() represents existing vault://... refs.

compile

tela workflow compile [target] loads Workflow Code config, selects a workflow target by the config workflows map key, evaluates the target entrypoint, and emits an inspectable compiled Workflow V3 payload. It is non-mutating: it does not call Tela APIs, write state, or publish versions.

Config loading evaluates workflow-code.config.ts after loading default .env files and any custom file passed with --env <path>. The --env flag is for dotenv files only; active Tela context selection remains owned by Tela Local auth/context state.

Source evaluation trust and reproducibility model

Workflow Code source evaluation is a local build step for trusted repositories. The workflow source files, local imports inside the source root, and installed npm packages imported while building declarations are trusted code. External package imports are loaded with Node createRequire() so package top-level code can run in the local compile process before exports are wrapped for VM use. Do not compile untrusted workflow source or untrusted installed dependencies.

For package reproducibility, the source hash records the exact installed package name/version and the package package.json snapshot. The reproducibility unit is the exact package version resolved from the lockfile/package manager, not arbitrary mutable local edits to files under node_modules at the same version. Use a clean install from a reviewed lockfile when reproducing a compile.

sync

Compiles local source and creates a consolidated Tela version through the API lifecycle contract. Without positional target, sync runs every configured workflow; pass target to sync only one workflow. Sync uses idempotency keys so retries are safe. Remote commands resolve the active Tela Local context through @meistrari/tela-local-config and select the matching contexts[...] binding from config for projectId and promptId.

Sync reads and writes one per-context lockfile per selected workflow at .tela/workflows/{workflowKey}/contexts/{contextKey}/lock.json. The lockfile records the selected context identity, last synced version, hashes, and the latest remote content snapshot used to detect remote divergence.

publish

Publishes only Tela version(s) proven to match local compiled source. Without positional target, publish runs for every configured workflow; with target, it runs only that config entry. --environment <name> selects one workflow publication environment for every selected workflow and defaults to production. Before any sync, consolidation, or publication, publish resolves the selected environment and its current remote version for every workflow. When a custom environment is missing in an interactive terminal, publish asks once whether to create it for all affected workflows and defaults to no. In --json or another non-interactive execution, pass --create-environment-if-missing to authorize creation explicitly. --yes remains limited to remote-divergence confirmation during the sync lifecycle and does not authorize environment creation. The environment flag does not select the Tela Local context, API endpoint, workspace, or credentials: those still come from shared Tela CLI auth and the active context binding. --env <path> remains only a dotenv loader.

For each workflow, publish releases the exact matching consolidated version through POST /environment/publish-by-name. A matching draft is first consolidated, then the same version ID is published to the selected environment. Proof requires local source/compiled hashes and the fresh remote version ID, version index, and content hash to match the active-context lockfile; equal content on a different remote version does not establish synced lineage. If that proof fails, publish invokes the normal sync lifecycle first and publishes the resulting exact version; pass --yes for non-interactive remote-divergence confirmation. A version published in one environment is not treated as published in another. Publish never edits a published/consolidated release in place or creates a version unrelated to local compiled source.

Publish does not persist publication state in the Workflow Code lockfile; Tela environment state is authoritative. --json reports the selected workflow environment identity and whether it was created, plus target/workflow/context identities, published version IDs, source/compiled/remote-content hashes, diagnostics, and paths written by an implicit sync, when one was required.

run

Runs synced workflow version selected by required positional target. Text inputs accept strings. File inputs accept local paths or supported remote file references; local files are uploaded before the run starts.

watch

Runs an initial compile, codegen, and sync cycle for the selected workflow(s), then watches local source files, the Workflow Code config file, and the active Tela Local config file. Without positional target, watch covers every configured workflow; pass target to watch only one config entry. Events are debounced and serialized: changes that arrive while a cycle is running coalesce into one follow-up cycle, so codegen and sync do not overlap.

Each cycle reloads config, so new targets, changed entries, and newly imported source files are picked up without restarting. Each cycle refreshes remote metadata through the same mechanism as codegen and syncs through the same lifecycle path as sync. Changing Tela contexts switches to that context's lockfile and human output reports the prior and new context; unchanged context cycles print no context-change notice. Watch ignores project .tela/ writes, including lockfiles, catalog snapshots, and generated augmentation files, so it cannot self-trigger. Watcher backend errors produce diagnostics, close the watcher, and exit non-zero. Ctrl+C stops the routed Tela CLI watch loop and cleans up the SIGINT handler.

CI example

pnpm install --frozen-lockfile
tela workflow codegen
tela workflow compile invoice-processing --json
tela workflow sync --json
tela workflow publish --json

Use authenticated commands only in trusted CI environments with Tela credentials configured.

Development in this repository

pnpm --filter @meistrari/workflow-code run typecheck
pnpm --filter @meistrari/workflow-code run test
pnpm --filter @meistrari/workflow-code run build
node apps/tela-cli/dist/index.js workflow help

Workflow V3 graph/reference/lifecycle/action schema contracts, action IDs, and reference URI formatting are consumed from @meistrari/workflow-shared.

Implementation docs for contributors and agents live in ../../docs/workflow-code/README.md, including the generated metadata documentation suite starting at ../../docs/workflow-code/generated-metadata.md.