@meistrari/tela-cli 0.8.0 → 1.0.0

package/dist/docs/workflow-code/api-reference.md

@@ -12,9 +12,13 @@ Import the authoring helpers from `@meistrari/workflow-code`.
 import {
     agent,
     build,
+    canvas,
     code,
     input,
     llm,
+    splitter,
+    vault,
+    remote,
     workflow,
 } from '@meistrari/workflow-code'
 import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
@@ -27,14 +31,18 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`input.text()`](#inputtextoptions) | Text input supplied by a user, API caller, or run payload. |
 | [`input.file()`](#inputfileoptions) | File input supplied by upload or Vault reference. |
 | [`llm()`](#llmoptions) | Single model-call transformation with optional structured output. |
-| [`agent()`](#agentoptions) | Multi-round reasoning, tool use, Tela tools, or external skills. |
+| [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
+| [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
+| [`remote()`](#remote) | Generated catalog paths and explicit ID refs for inert remote authoring. |
+| [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
+| [`agent(remoteRef, options)`](#agentremoteref-options) | Published-Agent calls from the remote catalog. |
 | [`code()`](#codeoptions) | Sandboxed runtime JavaScript/TypeScript execution. |
 | [`ref()` / `paths()` / `formats()`](#references-ref-paths-and-formats) | References to workflow inputs or prior node output in prompt callbacks and code handlers. |
 
 A workflow file normally creates inputs, creates nodes, then default-exports `build(workflow(...), { inputs, nodes })`.
 
 ```ts
-import { agent, build, input, llm, workflow } from '@meistrari/workflow-code'
+import { agent, build, input, llm, remote, workflow } from '@meistrari/workflow-code'
 
 const topic = input.text({ name: 'topic', required: true })
 
@@ -49,14 +57,16 @@ const outline = llm({
     },
 })
 
-const review = agent({
+const reviewer = remote().agent().byId('published-agent-id')
+
+const review = agent(reviewer, {
     name: 'Review outline',
     input: {
-        maxRounds: 8,
-        prompt: ({ ref, paths }) => [
+        message: ({ ref, paths }) => [
             'Review this outline for a new Tela user.',
             `Bullets: ${ref(outline, paths(outline).bullets).formats().format}`,
         ].join('\n'),
+        inputs: {},
     },
 })
 
@@ -74,6 +84,42 @@ Rules to keep in mind:
 - References in node inputs may target workflow inputs or earlier nodes. Forward references are compile diagnostics.
 
 
+### `remote()`
+
+```ts
+import { agent, build, canvas, input, remote, workflow } from '@meistrari/workflow-code'
+
+const document = input.file({ name: 'document', required: true })
+const extractInvoice = remote().canvas().Finance['Extract Invoice']
+const triage = remote().agent().byId('published-agent-id')
+
+const extract = canvas(extractInvoice, {
+    name: 'Extract invoice',
+    input: {
+        variables: ({ ref }) => ({ file: ref(document) }),
+    },
+})
+
+const classify = agent(triage, {
+    name: 'Triage extraction',
+    input: {
+        message: ({ ref }) => `Classify ${ref(extract).formats().parser}`,
+        inputs: ({ ref }) => ({ document: ref(document) }),
+    },
+})
+
+export default build(workflow('remote-catalog-example'), {
+    inputs: [document],
+    nodes: [extract, classify],
+})
+```
+
+Run `tela workflow codegen` before typechecking to generate named paths. User workflow source still imports only from `@meistrari/workflow-code`; generated catalog declarations augment those public types and should not be imported from workflow files.
+
+`remote()` values are inert path refs, not API calls or runtime resource objects. `remote().canvas()`, `.workflow()`, `.agent()`, and `.models()` expose generated namespaces. Use bracket access for names with spaces, punctuation, reserved words, or any other segment that is not a safe JavaScript identifier. `byId()` and model `raw()` are explicit escape hatches when a generated name is unavailable or an ID is clearer.
+
+`compile` preserves remote refs symbolically and remains offline. `sync` refreshes the active catalog, validates and locks referenced resources, resolves the refs, then lowers them for remote mutation.
+
 ### References: `ref()`, `paths()`, and `formats()`
 
 Workflow references connect node inputs to workflow inputs or earlier node outputs. Under the hood, Tela represents those links as URI references such as `input://customer_question` or `step://extract_invoice?path=total&format=...`. Workflow Code hides the URI string and exposes typed helpers instead.
@@ -102,7 +148,7 @@ const extractInvoice = llm({
     },
 })
 
-const reviewInvoice = agent({
+const reviewInvoice = llm({
     name: 'Review invoice extraction',
     input: {
         prompt: ({ ref, paths }) => [
@@ -296,58 +342,182 @@ const extractInvoice = llm({
 })
 ```
 
-### `agent(options)`
+### `canvas(remoteRef, options)`
 
 ```ts
-type AgentOptions = {
+type RemoteCanvasOptions<Ref extends WorkflowCodeRemoteExecutableRef, Environment extends RemoteEnvironment<Ref> | undefined = undefined> = {
     name: string
     key?: string
-    input: {
-        prompt: string | ((context: PromptFactoryContext) => string)
-        model?: string
-        maxRounds?: number
-        tools?: AgentToolOptions
-    }
-    schema?: WorkflowCodeOutputSchema | null
-}
-
-function agent(options: AgentOptions): AgentNodeDeclaration
+} & (Environment extends string
+    ? { environment: Environment, input: { variables: RemoteReferenceRecordInput<RemoteInputObject<Ref, Environment>> } }
+    : RemoteDefaultOptions<Ref>)
+
+function canvas<Ref extends WorkflowCodeRemoteExecutableRef, Environment extends RemoteEnvironment<Ref> | undefined = undefined>(
+    ref: Ref,
+    options: RemoteCanvasOptions<Ref, Environment>,
+): CanvasNodeHandle<RemoteSelectedOutput<Ref, Environment>>
 ```
 
-Declares an agent node. Use `agent()` when the step may need iteration, tool calls, Tela tools, or broader reasoning than a single completion.
+Declares an executable remote Canvas or Workflow node. The `remoteRef` must come from `remote().canvas()` or `remote().workflow()`. Generated metadata supplies known input variables, output fields, and environment choices when the catalog exposes them.
 
 | Option | Type | Required | Description |
 | --- | --- | --- | --- |
 | `name` | `string` | Yes | Display name and fallback node identity. Must be non-empty. |
 | `key` | `string` | No | Stable identity when `name` may change. |
-| `input.prompt` | `string \| (context) => string` | Yes | Agent instruction. Callback form enables `ref()` and `paths()`. Must render to non-empty string. |
-| `input.model` | `string` | No | Agent model id passed through to Workflow V3. |
-| `input.maxRounds` | `number` | No | Maximum reasoning/tool-use rounds. |
-| `input.tools` | `AgentToolOptions` | No | Built-in or platform tool options accepted by Workflow V3. |
-| `schema` | `WorkflowCodeOutputSchema \| null` | No | Structured output fields for the agent result. Use field names mapped to JSON-schema-like field definitions; omit for default behavior or set `null` when intentionally no schema should be emitted. |
+| `environment` | Generated literal union | Catalog-dependent | Environment name narrowed by the generated ref, such as `'production' \| 'staging'`. A generated ref with multiple non-production targets requires `environment`; generated refs with production metadata, no target metadata, or one selectable target may omit it. |
+| `input.variables` | `Record<string, unknown> \| (context) => Record<string, unknown>` | Yes | Variables passed to the remote executable. Callback form enables `ref()` and typed variable refs. |
 
-`schema` gives the agent an explicit result contract after reasoning/tool use and creates fields that downstream nodes can reference with `paths()`. Keep fields small and explicit: use `type`, `description`, `enum`, `properties`, `items`, and `required` when useful.
+Generated declarations narrow `environment` to catalog literal names and conditionally make it required; it is not an arbitrary `string` escape hatch. The signature above uses the named `RemoteCanvasOptions` shape because the exact requiredness depends on the generated ref's target metadata rather than on a universal optional or required overload. Use `byId()` only for explicit ID binding, then rely on `sync` for authenticated environment validation when generated metadata is unavailable or stale.
+
+After sync resolution, this becomes the existing Workflow V3 Canvas action with `canvasId`, optional `environmentName`, and resolved `variables`. Compile keeps the ref symbolic until orchestration supplies the active catalog and locks.
+
+### `splitter(options)`
 
 ```ts
-const reviewInvoice = agent({
-    name: 'Review invoice extraction',
-    key: 'review_invoice',
+type SplitterOptions = {
+    name: string
+    key?: string
     input: {
-        maxRounds: 6,
-        prompt: ({ ref, paths }) => [
-            'Review extracted invoice data for missing or suspicious fields.',
-            `Vendor: ${ref(extractInvoice, paths(extractInvoice).vendor).formats().format}`,
-            `Total: ${ref(extractInvoice, paths(extractInvoice).total).formats().format}`,
-        ].join('\n'),
+        file: WorkflowCodeExclusiveFileSource
+        chunkSize?: number
+        type?: 'pdf' | 'csv'
+        mode?: 'single-pages' | 'smart-files'
+        customPrompt?: string
+        customPromptMode?: 'always' | 'fallback'
+    }
+}
+
+function splitter(options: SplitterOptions): SplitterNodeHandle
+```
+
+Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()`, or an array of Vault refs. It does not accept arbitrary strings or text references.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Display name and fallback node identity. |
+| `key` | `string` | No | `name` | Stable identity when the display name may change. |
+| `input.file` | `WorkflowCodeExclusiveFileSource` | Yes | — | File/File-array workflow reference, `vault.ref()`, or array of Vault refs. |
+| `input.chunkSize` | `number` | No | `1` | Pages per PDF chunk or rows per CSV chunk. |
+| `input.type` | `'pdf' \| 'csv'` | No | `'pdf'` | Splitter document type. |
+| `input.mode` | `'single-pages' \| 'smart-files'` | No | `'single-pages'` | Fixed chunking or smart document-boundary detection. |
+| `input.customPrompt` | `string` | No | — | Optional smart-files instruction, up to 2,000 characters. |
+| `input.customPromptMode` | `'always' \| 'fallback'` | No | `'always'` | Whether the custom smart-files prompt is always used or only as fallback. |
+
+```ts
+const invoice = input.file({
+    name: 'invoice',
+    required: true,
+})
+
+const pages = splitter({
+    name: 'Split invoice',
+    input: {
+        file: ({ ref }) => ref(invoice),
+        chunkSize: 1,
+        type: 'pdf',
+    },
+})
+
+const splitFirstPageAgain = splitter({
+    name: 'Split first page again',
+    input: {
+        file: ({ ref, paths }) => ref(pages, paths(pages)[0].file),
     },
+})
+```
+
+Structured `llm()` outputs and published Agent outputs from `agent(remoteRef, options)` are valid sources only when the selected output or path has a file-compatible schema. A file schema declares string-valued schemas for `name` and at least one locator property (`fileUrl`, `vaultReference`, or `base64`). Any other declared transport string field (`mimeType` or another locator) must also be string-valued. Arrays are compatible when their item schema is file-compatible. The `x-tela-kind: 'file'` marker is metadata only and does not bypass structural validation. Schema presence or matching property names alone is not sufficient: scalar, generic-object, missing, malformed, or otherwise incompatible paths produce `compiler.ref.incompatible`.
+
+```ts
+const generated = llm({
+    name: 'Generate document reference',
+    input: { prompt: 'Return the generated document reference.' },
     schema: {
-        approved: { type: 'boolean' },
-        notes: { type: 'array', items: { type: 'string' } },
+        document: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                fileUrl: { type: 'string' },
+            },
+        },
+    },
+})
+
+const generatedPages = splitter({
+    name: 'Split generated document',
+    input: {
+        file: ({ ref, paths }) => ref(generated, paths(generated).document),
     },
 })
 ```
 
-Choose `agent()` over `llm()` when the workflow step needs investigation, retries, tools, or judgment across multiple pieces of context.
+`code()` outputs can also feed `splitter.input.file`. Compile statically infers the original handler return without calling it. Transport-file objects, nested paths, file arrays, pass-through file refs, and `File`/`Blob` values are supported. Scalar, malformed, `any`, `unknown`, and mixed file/non-file returns produce `compiler.ref.incompatible`.
+
+```ts
+const generatedByCode = code({
+    name: 'Generate document in code',
+    handler: () => new File(['document contents'], 'generated.pdf', {
+        type: 'application/pdf',
+    }),
+})
+
+const generatedCodePages = splitter({
+    name: 'Split code document',
+    input: {
+        file: ({ ref }) => ref(generatedByCode),
+    },
+})
+```
+
+The referenced runtime value still needs to describe a real file. Declaring `fileUrl` or `vaultReference` in an LLM schema does not upload or create a Vault file.
+
+### `vault.ref(reference)`
+
+```ts
+const vault: {
+    ref: <Reference extends `vault://${string}`>(
+        reference: Reference,
+    ) => WorkflowCodeVaultRef<Reference>
+}
+```
+
+Creates an inert declaration for a file that already exists in Vault. The reference must contain a UUID v4 or SHA-256 file id. Calling `vault.ref()` does not read credentials, contact Vault, download the file, or mutate local state during source evaluation.
+
+```ts
+const existingInvoice = vault.ref(
+    'vault://550e8400-e29b-41d4-a716-446655440000',
+)
+
+const existingPages = splitter({
+    name: 'Split existing invoice',
+    input: { file: existingInvoice },
+})
+```
+
+During compile, a direct Vault ref used by `splitter.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
+
+### `agent(remoteRef, options)`
+
+```ts
+function agent<Ref extends WorkflowCodeRemoteAgentRef>(
+    ref: Ref,
+    options: {
+        name: string
+        key?: string
+        input: {
+            message: string | ((context: PromptFactoryContext) => string)
+            inputs: Record<string, unknown> | ((context: PromptFactoryContext) => Record<string, unknown>)
+            environmentVariables?: Record<string, string>
+        }
+    },
+): AgentNodeHandle<RemoteAgentOutput<Ref>>
+```
+
+Declares a published Agent invocation. The `remoteRef` must come from `remote().agent()`. Generated metadata supplies known required inputs and output types when the catalog contains an authoritative published-Agent contract.
+
+`input.message` is prompt-like, may use `ref()` callbacks, and must render to a non-empty string. `input.inputs` supplies the published Agent's named inputs and may contain workflow input or prior-node refs. Optional `environmentVariables` remain authored strings; they are not resolved through catalog metadata.
+
+Lowering targets the existing Workflow V3 `agent-fcc` action fields `agentId`, `message`, `inputs`, and optional `environmentVariables` only. It does not emit output schema, revision, or catalog-hash fields in the node input.
 
 ### `code(options)`
 

package/dist/docs/workflow-code/cli.md

@@ -1,6 +1,6 @@
 ## CLI
 
-The workflow command group documents implemented `init`, `compile`, `docs`, `sync`, and `publish` workflows. Current MVP behavior is local-first until you run explicit remote lifecycle commands such as `sync` or `publish`.
+The workflow command group documents implemented `init`, `compile`, `docs`, `codegen`, `sync`, and `publish` workflows. Current MVP behavior is local-first until you run explicit remote lifecycle commands such as `sync` or `publish`.
 
 ### Command surface
 
@@ -9,6 +9,7 @@ The workflow command group documents implemented `init`, `compile`, `docs`, `syn
 | `init [--directory <path>] [--config <path>] [--workflow <key>...] [--yes] [--init-git\|--no-init-git] [--install-deps\|--no-install-deps] [--package-manager bun\|pnpm\|npm\|yarn] [--json]` | Implemented | No | Create local Workflow Code scaffold. |
 | `compile [target] [--config <path>] [--env <path>] [--json]` | Implemented | No | Compile selected source into Workflow V3 output. |
 | `docs [page] [--json]` | Implemented | No | Read the version-matched Workflow Code documentation bundled with the installed CLI. |
+| `codegen [--json]` | Implemented | No | Refresh or reuse the active-context remote catalog and generate remote() TypeScript metadata. |
 | `sync [target] [--config <path>] [--env <path>] [--yes] [--json]` | Implemented | Yes | Synchronize local compiled workflow(s) with configured Tela prompt(s). |
 | `publish [target] [--environment <name>] [--create-environment-if-missing] [--config <path>] [--env <path>] [--yes] [--json]` | Implemented | Yes | Publish local-matching workflow version(s) to the selected workflow environment. |
 
@@ -21,6 +22,7 @@ tela workflow compile
 tela workflow compile invoice-processing
 tela workflow compile invoice-processing --env .env.staging --json
 tela workflow docs cli
+tela workflow codegen --json
 tela workflow sync
 tela workflow sync invoice-processing --env .env.staging --json
 tela workflow publish
@@ -105,6 +107,27 @@ tela workflow docs cli
 tela workflow docs api-reference --json
 ```
 
+### codegen
+
+`codegen [--json]`
+
+**Description.** `tela workflow codegen` resolves the active Tela Local context and workspace, refreshes the authenticated remote catalog, and writes TypeScript metadata for inert `remote()` authoring. It writes the generated augmentation at `.tela/workflow-code/generated/workflow-code.generated.d.ts` and the complete context/workspace snapshot at `.tela/workflow-code/catalogs/<workspaceId>/remote-catalog.snapshot.json`. The catalog includes canvases, workflows, templates, published agents, and models; only canvases, workflows, published agents, and models are projected by `remote()`.
+
+Codegen fetches a fresh snapshot when possible. If refresh fails, it may reuse only a complete cached snapshot for the same active context and workspace, reports warning diagnostics, and repairs or skips artifacts deterministically. If neither refresh nor a matching snapshot is available, it fails without inventing catalog bindings. Generated files are non-secret typechecking and orchestration metadata; include the generated declaration path in TypeScript's `include` configuration when needed.
+
+`compile` remains offline and preserves symbolic remote refs. `sync` refreshes and validates catalog references and locks before resolved lowering and remote mutation.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `--json` | Flag | No | Emit command, active context/workspace, metadata source/hash/timestamps, written paths, skipped paths, and diagnostics as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow codegen
+tela workflow codegen --json
+```
+
 ### sync
 
 **Description.** `tela workflow sync` compiles local source, resolves the active Tela Local context, selects the matching `projectId` and `promptId`, verifies remote content, and writes per-context lockfile state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`.

package/dist/docs/workflow-code/manifest.json

@@ -8,19 +8,19 @@
       "slug": "overview",
       "title": "Documentation overview",
       "file": "overview.md",
-      "sha256": "864146c6f6ef204590c4f444edb5109be08075343bd3115f1ba5bc29d70be177"
+      "sha256": "88c838262048260cee280cdd8d16e9987847bcf06b857ca6d2cf0b707c4b15fe"
     },
     {
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "bc52ff31a4fcf5b8c21cf0ddf2fc3f2ba2dcbc69b6b55302f26768fb5348b7bb"
+      "sha256": "2306f6a21d23b4e3457262c3105e65e0292af5a59154aa15cf24188409db07f8"
     },
     {
       "slug": "cli",
       "title": "CLI",
       "file": "cli.md",
-      "sha256": "321454c8359c0449261e625120e2af6960cc71460dcf9a0f929ffad58e8ab4bf"
+      "sha256": "759db330fd7b06859e55404f01feb0625a43bb579324fe011bc34cd92d517239"
     },
     {
       "slug": "config",
@@ -44,7 +44,7 @@
       "slug": "quick-start",
       "title": "Quick start",
       "file": "quick-start.md",
-      "sha256": "78212b3f1fa52c116e6fd9f5331edefecf1079e1073aa32673f719b44d019ce8"
+      "sha256": "15f4b45bd6292c4dd3f3ff5fc58f46e5e83e55f3a5e4ed9fee0df37fd12b2305"
     }
   ]
 }

package/dist/docs/workflow-code/overview.md

@@ -9,6 +9,6 @@ Workflow Code documentation is organized as a set of focused pages. Read the pag
 | [Quick start](/docs/quick-start) | You want the shortest path from `tela workflow init` to local compile and explicit sync. |
 | [Installation](/docs/installation) | You need to verify Tela Dock, the `tela` CLI, or the `@meistrari/workflow-code` package. |
 | [Config](/docs/config) | You are defining `workflow-code.config.ts`, dotenv files, target ids, or context-specific bindings. |
-| [CLI](/docs/cli) | You need implemented init/compile/sync/publish behavior, target selection rules, or JSON diagnostics. |
-| [API Reference](/docs/api-reference) | You are authoring `workflow()`, `build()`, `input`, `llm`, `agent`, `code`, and references. |
+| [CLI](/docs/cli) | You need implemented init/compile/docs/codegen/sync/publish behavior, target selection rules, generated catalog refresh, or JSON diagnostics. |
+| [API Reference](/docs/api-reference) | You are authoring `workflow()`, `build()`, `input`, `llm`, `agent`, `code`, references, remote catalogs, and executable remote refs. |
 | [Guides](/docs/guides) | You want repository layout, CI compile checks, and troubleshooting patterns. |

package/dist/docs/workflow-code/quick-start.md

@@ -47,7 +47,7 @@ Keep the first config small: one target, one entrypoint, and environment-backed
 ### Author a workflow
 
 ```ts
-import { agent, build, code, input, llm, workflow } from '@meistrari/workflow-code'
+import { agent, build, code, input, llm, remote, workflow } from '@meistrari/workflow-code'
 
 const topic = input.text({
     name: 'topic',
@@ -77,15 +77,17 @@ const countBullets = code({
     },
 })
 
-const review = agent({
+const reviewer = remote().agent().byId('published-agent-id')
+
+const review = agent(reviewer, {
     name: 'Review outline',
     input: {
-        maxRounds: 8,
-        prompt: ({ ref, paths }) => [
+        message: ({ ref, paths }) => [
             'Review this outline for a new Tela user.',
             `Bullets: ${ref(outline, paths(outline).bullets).formats().json}`,
             `Bullet count: ${ref(countBullets, paths(countBullets).count).formats().json}`,
         ].join('\n'),
+        inputs: {},
     },
 })