workflow

kylon workspace workflow — kylon workspace help detail

workflow — automated workflows in this room
  Workflow runs are non-blocking: public-output workflows can use kylon workspace ui send for read-only cards or bounded human input, but a run does not pause in-place to wait for a reply. If a user interacts with a workflow card, a continuation turn resumes the workflow session with the submitted result.
  kylon workspace workflow list [--room <name_or_id|all|current>] [--query <keyword>]
    IMPORTANT: omit --room to search the current room only. Use --room all
            for workspace-wide workflow search across all visible rooms, or a
            specific room name/ID to search one room.
    --query: case-insensitive substring match on workflow name (SQL-side via trigram).
  kylon workspace workflow show <workflow_id>         show full workflow configuration and prompt
  kylon workspace workflow create --name <name> [--task <text> --context <text> | --message <text>] [--schedule <json> | --trigger webhook --provider <generic|github>] [--expect <text>] [--publish [--activate-output [agent_id]] [--mention-mode <forced|routed>]] [--timezone <tz>]
    schedule format: {"kind":"cron","expr":"0 9 * * *"} | {"kind":"every","everyMs":3600000} | {"kind":"at","at":"2026-04-01T09:00:00Z"} | {"kind":"app_record_change","appId":"<app_id>","entityId":"<entity_id>","events":["insert","update","delete"]}
    omit --schedule for manual-only workflows
    --timezone: IANA name like "Asia/Shanghai". Cron expr is interpreted in this timezone — do NOT pre-convert to UTC. Defaults to UTC.
    Creation checklist:
      1. Put the complete behavior in the saved workflow definition. For deterministic reusable logic, use a self-contained TypeScript body that imports @kylon/workflow-sdk; the saved immutable revision persists that source.
      2. Local files under /home/user are disposable authoring or per-run scratch. You may prepare code under /home/user/automations. Never make a workflow depend on that path surviving into a later run.
      3. For workflows that perform work, implement and test the process outside the scheduler before saving it, or document why that cannot be done. Then save the complete tested source with --message. Do not save only an instruction to run an unpersisted local script.
      4. Verify the expected result. If pre-validation is impossible or not useful, say why and include the validation the workflow run should perform.
      5. A prompt workflow should include: goal, trigger assumptions, execution steps, expected output, validation method, and what to report when blocked or validation fails.
      6. Persist cross-run state with the workflow state tools and durable outputs with publish_workflow_file; do not use a local database as the only copy of state.
      7. Use --expect to describe the expected run result format.
    Body choice:
      - Use CODE for a fixed procedure with deterministic control flow around scoped agent() calls, including parallel fan-out, branching on ctx.trigger, or a fixed sequence of reasoning steps. Keep work that does not need judgment as plain code.
      - Use a PROMPT for open-ended, judgment-dominant work, managed connection or data-write operations, and App-record triggers.
    Code workflows: a body that imports '@kylon/workflow-sdk' is stored and run as TypeScript
      instead of a prompt. It runs as a TOP-LEVEL module (top-level await works; a default
      export is never invoked and is rejected at save time). Available imports are:
      - ctx: workspaceId, roomId, agentId, now(), timezone, and trigger. Narrow on ctx.trigger.kind before reading its payload. Webhook triggers expose provider, method, headers, bodyJson/bodyText, and receivedAt.
      - agent(prompt, { schema? }): the only token-spending call; it is read-only and returns its result to the script.
      - parallel(thunks) and pipeline(items, ...stages): bounded-concurrency control flow.
      - sendMessage(text, { mention? }): queue explicit messages to the workflow's own room.
      connection and state are not available yet and throw if called. A code workflow cannot write data or call a managed connection; use a prompt workflow for that. Code workflows cannot use App-record triggers yet; webhook triggers are supported.
      Output: stdout becomes the run output. If sendMessage is called, its queued messages are the output and stdout is not also posted. Messages appear when the run finishes, not mid-run, and are discarded if the script throws. Output is posted only with --publish. This surface cannot dry-run code workflows. Keep the first revision free of destructive side effects, then inspect kylon workspace workflow runs <workflow_id> after its first run before relying on it.
    Delivery policy: for normal public workflow results, use --publish so runs post to the room's flat chat. Omit --publish only for internal/run-history-only workflows.
    Use private or targeted delivery only when the user explicitly asks, or when output is sensitive, noisy, or user-specific.
    Output handoff: add --activate-output when that published final result should itself be the single room root of a newly activated agent thread. Bare --activate-output follows the room's current main agent; pass an agent ID to pin a target. --mention-mode forced (default) requires a response; routed allows the target to stay silent. This is prompt-workflow-only. Do not also call thread create for the same result.
    Scheduled workflows must respect the platform minimum interval: production 10 minutes, development 5 minutes, unless WORKFLOW_MIN_INTERVAL_MS overrides it. Cron schedules are rejected when sampled adjacent fire times are closer than the minimum.
    app_record_change: fires when matching Database App records are inserted, updated, or deleted. Use 'app docs' or Data Viewer schema to find the appId and entityId. Events array must contain at least one of: insert, update, delete.
    webhook: creates a capability-token endpoint and returns a copyable webhook URL. Use --message for code that branches on ctx.trigger, --message for a direct prompt, or --task/--context to render one.
    --expect: describe expected output format
    --publish: publish run results to room flat chat.
  kylon workspace workflow update <workflow_id> [--name <name>] [--message <text> | --task <text> --context <text>] [--schedule <json>] [--expect <text>] [--publish] [--timezone <tz>]
    Use --message to replace the raw workflow prompt and clear structured task/context fields.
    --publish: publish future run results to room flat chat.
  kylon workspace workflow webhook show <workflow_id>
  kylon workspace workflow webhook rotate <workflow_id>
  kylon workspace workflow webhook revoke <workflow_id>
  kylon workspace workflow runs <workflow_id>        show execution history
    When a workflow behaves incorrectly, inspect workflow show and recent workflow runs before changing it.
  kylon workspace workflow runs show <run_id> [--step <n>]   show detailed run output and execution steps
    --step: expand the full result of step N (1-based index from the step list)
  kylon workspace workflow runs show --workflow <workflow_id> --correlation <run_handle>
    Show the run started by a specific kylon workspace workflow trigger, using the run handle it
    returned. Prefer this over guessing the newest run. Runs are async: right after
    triggering this reports the run is queued — check again in a few seconds.
  kylon workspace credit budget show --scope workflow --id <workflow_id>
    Show the budget policy for one workflow.
  kylon workspace credit budget set --scope workflow --id <workflow_id> [--daily <credits|default>] [--weekly <credits|default>] [--monthly <credits|default>] [--action warn|pause] [--status active|disabled]
    Update the budget policy for one workflow.
  kylon workspace credit script
    Show the workspace code-run API credit limits used by code this workflow may run.
  kylon workspace workflow trigger <workflow_id>     manually run a workflow now; returns a run
    handle — read that run with kylon workspace workflow runs show --workflow <workflow_id>
    --correlation <run_handle>
  kylon workspace workflow pause <workflow_id>       stop scheduled triggers (manual trigger still works)
  kylon workspace workflow resume <workflow_id>      re-enable scheduled triggers
  kylon workspace workflow archive <workflow_id>
Resource link handoff:
- Emit identified Kylon resources as clickable, path-only markdown links with human-readable labels.
- Copy command-returned links verbatim. Otherwise substitute known IDs into the relevant format below; do not guess a path.
- Workflow: `[name](/workspaces/{workspaceId}/rooms/{roomId}/workflows/{workflowId})`

Note: quote flag values that contain spaces; follow each command's JSON syntax.