@opendash-ai/cli 0.1.0-beta.1 → 0.1.0-beta.3

package/src/tool/websearch/index.ts

@@ -1,104 +0,0 @@
-import z from "zod"
-import { Effect } from "effect"
-import { HttpClient } from "effect/unstable/http"
-import * as Tool from "../tool"
-import * as McpExa from "../mcp-exa"
-import * as MimoWebsearch from "./mimo"
-import { Auth } from "@/auth"
-import { Provider } from "@/provider"
-import DESCRIPTION from "./websearch.txt"
-
-const WEBFETCH_FALLBACK =
-  "Web search unavailable. Use `webfetch` with a relevant URL instead, or enable the Web Search plugin at https://opendash.ai."
-const MAX_TIMEOUT = 120 * 1000 // 2 minutes
-
-const Parameters = z.object({
-  query: z.string().describe("Websearch query"),
-  numResults: z.number().optional().describe("Number of search results to return (default: 8)"),
-  timeout: z.number().describe("Optional timeout in seconds (max 120)").optional(),
-  livecrawl: z
-    .enum(["fallback", "preferred"])
-    .optional()
-    .describe(
-      "Live crawl mode - 'fallback': use live crawling as backup if cached content unavailable, 'preferred': prioritize live crawling (default: 'fallback')",
-    ),
-  type: z
-    .enum(["auto", "fast", "deep"])
-    .optional()
-    .describe("Search type - 'auto': balanced search (default), 'fast': quick results, 'deep': comprehensive search"),
-  contextMaxCharacters: z
-    .number()
-    .optional()
-    .describe("Maximum characters for context string optimized for LLMs (default: 10000)"),
-})
-
-export const WebSearchTool = Tool.define(
-  "websearch",
-  Effect.gen(function* () {
-    const http = yield* HttpClient.HttpClient
-    const auth = yield* Auth.Service
-
-    return {
-      get description() {
-        return DESCRIPTION.replace("{{year}}", new Date().getFullYear().toString())
-      },
-      parameters: Parameters,
-      execute: (params: z.infer<typeof Parameters>, ctx: Tool.Context) =>
-        Effect.gen(function* () {
-          yield* ctx.ask({
-            permission: "websearch",
-            patterns: [params.query],
-            always: ["*"],
-            metadata: {
-              query: params.query,
-              numResults: params.numResults,
-              livecrawl: params.livecrawl,
-              type: params.type,
-              contextMaxCharacters: params.contextMaxCharacters,
-              timeout: params.timeout,
-            },
-          })
-
-          const model = (ctx.extra as { model?: Provider.Model })?.model
-          const timeout = params.timeout === undefined ? undefined : Math.min(params.timeout * 1000, MAX_TIMEOUT)
-
-          const result =
-            model?.providerID === "xiaomi"
-              ? yield* Effect.catchCause(
-                  Effect.gen(function* () {
-                    const info = yield* auth.get("xiaomi")
-                    if (!info || info.type !== "api") return undefined
-                    return yield* MimoWebsearch.call(
-                      http,
-                      model.api.url,
-                      info.key,
-                      params.query,
-                      "mimo-v2.5",
-                      timeout ?? "30 seconds",
-                    )
-                  }),
-                  () => Effect.succeed(undefined),
-                )
-              : yield* McpExa.call(
-                  http,
-                  "web_search_exa",
-                  McpExa.SearchArgs,
-                  {
-                    query: params.query,
-                    type: params.type || "auto",
-                    numResults: params.numResults || 8,
-                    livecrawl: params.livecrawl || "fallback",
-                    contextMaxCharacters: params.contextMaxCharacters,
-                  },
-                  timeout ?? "25 seconds",
-                )
-
-          return {
-            output: result ?? WEBFETCH_FALLBACK,
-            title: `Web search: ${params.query}`,
-            metadata: {},
-          }
-        }).pipe(Effect.orDie),
-    }
-  }),
-)

package/src/tool/websearch/mimo.ts

@@ -1,118 +0,0 @@
-import { Duration, Effect, Schema, Stream } from "effect"
-import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
-
-const DEFAULT_BASE_URL = "https://opendash.ai/zen/v1"
-
-export const QUOTA_EXCEEDED =
-  "Web search quota exhausted (free tier limit reached). Top up or manage your plan at https://opendash.ai, or use `webfetch` with a relevant URL instead."
-
-const Annotation = Schema.Struct({
-  type: Schema.optional(Schema.NullOr(Schema.String)),
-  url: Schema.optional(Schema.NullOr(Schema.String)),
-  title: Schema.optional(Schema.NullOr(Schema.String)),
-  summary: Schema.optional(Schema.NullOr(Schema.String)),
-  site_name: Schema.optional(Schema.NullOr(Schema.String)),
-  publish_time: Schema.optional(Schema.NullOr(Schema.String)),
-})
-type Annotation = Schema.Schema.Type<typeof Annotation>
-
-const Annotations = Schema.Array(Annotation)
-
-const Frame = Schema.Struct({
-  choices: Schema.optional(
-    Schema.Array(
-      Schema.Struct({
-        delta: Schema.optional(
-          Schema.NullOr(
-            Schema.Struct({
-              annotations: Schema.optional(Schema.NullOr(Annotations)),
-            }),
-          ),
-        ),
-        message: Schema.optional(
-          Schema.NullOr(
-            Schema.Struct({
-              annotations: Schema.optional(Schema.NullOr(Annotations)),
-            }),
-          ),
-        ),
-      }),
-    ),
-  ),
-})
-
-const decodeFrame = Schema.decodeUnknownEffect(Schema.fromJsonString(Frame))
-
-function buildUrl(baseUrl: string) {
-  const base = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "")
-  if (base.endsWith("/chat/completions")) return base
-  return (base.endsWith("/v1") ? base : `${base}/v1`) + "/chat/completions"
-}
-
-function formatSources(annotations: ReadonlyArray<Annotation>) {
-  const lines = annotations.flatMap((a) => {
-    if (!a.url) return []
-    const head = [a.title, a.site_name, a.publish_time].filter(Boolean).join(" · ")
-    return [`- ${head || a.url}`, `  ${a.url}`, ...(a.summary ? [`  ${a.summary}`] : [])]
-  })
-  return lines.length > 0 ? ["Sources:", ...lines].join("\n") : undefined
-}
-
-function extractAnnotations(line: string): Effect.Effect<ReadonlyArray<Annotation> | undefined> {
-  if (!line.startsWith("data:")) return Effect.succeed(undefined)
-  const payload = line.slice(5).trim()
-  if (!payload || payload === "[DONE]") return Effect.succeed(undefined)
-  return decodeFrame(payload).pipe(
-    Effect.map((frame) => {
-      const choice = frame.choices?.[0]
-      const list = choice?.delta?.annotations ?? choice?.message?.annotations
-      return list && list.length > 0 ? list : undefined
-    }),
-    Effect.orElseSucceed(() => undefined),
-  )
-}
-
-export const call = (
-  http: HttpClient.HttpClient,
-  baseUrl: string,
-  apiKey: string,
-  query: string,
-  modelId: string,
-  timeout: Duration.Input,
-) =>
-  Effect.gen(function* () {
-    const request = HttpClientRequest.post(buildUrl(baseUrl)).pipe(
-      HttpClientRequest.setHeader("api-key", apiKey),
-      HttpClientRequest.accept("text/event-stream"),
-      HttpClientRequest.bodyJsonUnsafe({
-        model: modelId,
-        messages: [{ role: "user", content: query }],
-        tools: [{ type: "web_search", max_keyword: 3, force_search: true, limit: 5 }],
-        max_completion_tokens: 256,
-        temperature: 1.0,
-        top_p: 0.95,
-        stream: true,
-        thinking: { type: "disabled" },
-      }),
-    )
-
-    const annotations = yield* HttpClientResponse.stream(HttpClient.filterStatusOk(http).execute(request)).pipe(
-      Stream.decodeText(),
-      Stream.splitLines,
-      Stream.mapEffect(extractAnnotations),
-      Stream.filter((value): value is ReadonlyArray<Annotation> => value !== undefined),
-      Stream.runHead,
-      Effect.catchIf(
-        (err) => err.reason._tag === "StatusCodeError" && err.reason.response.status === 409,
-        () => Effect.succeed(QUOTA_EXCEEDED),
-      ),
-      Effect.timeoutOrElse({
-        duration: timeout,
-        orElse: () => Effect.die(new Error("xiaomi web_search request timed out")),
-      }),
-    )
-
-    if (typeof annotations === "string") return annotations
-    if (annotations._tag === "None") return undefined
-    return formatSources(annotations.value)
-  })

package/src/tool/websearch/websearch.txt

@@ -1,14 +0,0 @@
-- Search the web - performs real-time web searches and can scrape content from specific URLs
-- Provides up-to-date information for current events and recent data
-- Supports configurable result counts and returns the content from the most relevant websites
-- Use this tool for accessing information beyond knowledge cutoff
-- Searches are performed automatically within a single API call
-
-Usage notes:
-  - Supports live crawling modes: 'fallback' (backup if cached unavailable) or 'preferred' (prioritize live crawling)
-  - Search types: 'auto' (balanced), 'fast' (quick results), 'deep' (comprehensive search)
-  - Configurable context length for optimal LLM integration
-  - Domain filtering and advanced search options available
-
-The current year is {{year}}. You MUST use this year when searching for recent information or current events
-- Example: If the current year is 2026 and the user asks for "latest AI news", search for "AI news 2026", NOT "AI news 2025"

package/src/tool/workflow.ts

@@ -1,357 +0,0 @@
-import * as Tool from "./tool"
-import DESCRIPTION from "./workflow.txt"
-import z from "zod"
-import { Effect, Fiber } from "effect"
-import { Config } from "../config"
-import { ConfigCompose } from "../config"
-import { InstanceState } from "@/effect"
-import { workflowRef } from "@/workflow/runtime-ref"
-import { BuiltinWorkflow } from "@/workflow/builtin"
-import type { SessionID } from "../session/schema"
-
-const id = "workflow"
-
-// Mirror compose.js arg normalization: a bare task string OR a JSON string both
-// collapse to an object. Used so host-side docs-dir injection can merge into args
-// regardless of how the caller serialized them.
-function parseComposeArgString(raw: string): Record<string, unknown> {
-  try {
-    const parsed = JSON.parse(raw)
-    if (typeof parsed === "object" && parsed !== null) return parsed as Record<string, unknown>
-  } catch {}
-  return { task: raw }
-}
-
-const runSchema = z.strictObject({
-  operation: z.literal("run"),
-  name: z
-    .string()
-    .min(1)
-    .optional()
-    .describe(
-      '(optional) Name of a built-in workflow to run (e.g. "deep-research"). Provide EITHER name OR script, not both.',
-    ),
-  script: z
-    .string()
-    .min(1)
-    .optional()
-    .describe(
-      "(optional) Inline JS workflow script; must begin with `export const meta = {...}`. Provide EITHER name OR script, not both.",
-    ),
-  args: z.any().optional().describe("(optional) JSON value exposed to the script as `args`."),
-  workspace: z
-    .string()
-    .optional()
-    .describe(
-      "(optional) Absolute dir the script's file primitives (readFile/writeFile/glob/exists) are jailed to. Defaults to the project worktree.",
-    ),
-  async: z
-    .boolean()
-    .optional()
-    .describe(
-      "(optional) When true, return a run_id immediately and let the workflow run in the background; the result arrives later as an inbox notification. Default false: block until terminal and return the transcript inline (skill-like semantics, recommended for short workflows).",
-    ),
-})
-const statusSchema = z.strictObject({ operation: z.literal("status"), run_id: z.string().min(1) })
-const waitSchema = z.strictObject({
-  operation: z.literal("wait"),
-  run_id: z.string().min(1),
-  timeout_ms: z.number().int().positive().optional(),
-})
-const cancelSchema = z.strictObject({ operation: z.literal("cancel"), run_id: z.string().min(1) })
-const resumeSchema = z.strictObject({ operation: z.literal("resume"), run_id: z.string().min(1) })
-
-export const parameters = z.discriminatedUnion("operation", [
-  runSchema,
-  statusSchema,
-  waitSchema,
-  cancelSchema,
-  resumeSchema,
-])
-
-type TranscriptEntry = { kind: "phase" | "log"; text: string }
-// `counters` and `currentPhase` are streamed in each flush so the inline
-// conversation panel shows live progress without polling: the bus run row only
-// carries counters via loadWorkflows (which only the /workflows dialog polls), so
-// without this the in-conversation panel would sit at 0✓ 0✗ 0⟳ for the whole run.
-type Metadata = {
-  runID?: string
-  status?: string
-  transcript?: TranscriptEntry[]
-  counters?: { running: number; succeeded: number; failed: number }
-  currentPhase?: string
-}
-
-// Bound the transcript that gets surfaced to the model (tool output) AND persisted
-// to part-state metadata AND streamed in each flush. A chatty workflow
-// (deep-research emits a phase + log per source) can otherwise feed tens of KB into
-// the model's context, grow the session file without bound, and — because each
-// flush pushes a full snapshot through ctx.metadata — make streaming O(N²) in event
-// count. Capping the snapshot to head + tail keeps every flush O(1) (so total
-// streamed bytes are O(run duration), not O(N²)) and the persisted/displayed view
-// bounded, while still showing the start and the most-recent activity.
-const TRANSCRIPT_HEAD = 40
-const TRANSCRIPT_TAIL = 160
-function capTranscript(t: readonly TranscriptEntry[]): TranscriptEntry[] {
-  if (t.length <= TRANSCRIPT_HEAD + TRANSCRIPT_TAIL + 1) return t.slice()
-  const omitted = t.length - TRANSCRIPT_HEAD - TRANSCRIPT_TAIL
-  return [
-    ...t.slice(0, TRANSCRIPT_HEAD),
-    { kind: "log", text: `…(${omitted} lines omitted)` },
-    ...t.slice(t.length - TRANSCRIPT_TAIL),
-  ]
-}
-
-export const WorkflowTool = Tool.define<typeof parameters, Metadata, Config.Service>(
-  id,
-  Effect.gen(function* () {
-    const config = yield* Config.Service
-
-    // Resolve the WorkflowRuntime through the late-bound workflowRef rather than as
-    // a Layer dependency: pulling WorkflowRuntime.Service in here would push that
-    // requirement onto ToolRegistry.layer, forcing every layer that builds the
-    // registry to provide it. The ref is populated by WorkflowRuntime.layer's
-    // initialiser (see workflow/runtime-ref.ts) — mirrors the actor tool's spawnRef.
-    const requireRuntime = () => {
-      const runtime = workflowRef.current
-      if (!runtime) {
-        return Effect.fail(
-          new Error(
-            "Workflow runtime unavailable — WorkflowRuntime.defaultLayer must be running for the workflow tool",
-          ),
-        )
-      }
-      return Effect.succeed(runtime)
-    }
-
-    // Thread the operator-configured compose docs dir into the `compose` built-in's
-    // args, mirroring the `<compose_docs_dir>` block prompt.ts injects for the
-    // interactive compose agent. The compose guest reads `args._composeDocsDir` and
-    // tells its plan/report subagents where to write specs/plans/reports. We
-    // normalize args the same way compose.js does (object | JSON-string | bare task
-    // string) so the injection survives the AI-SDK string-serialization boundary.
-    const enrichComposeArgs = (raw: unknown) =>
-      Effect.gen(function* () {
-        const ctx = yield* InstanceState.context
-        const docs = ConfigCompose.resolveDocsDir(ctx.worktree, (yield* config.get()).compose)
-        const base =
-          typeof raw === "object" && raw !== null
-            ? (raw as Record<string, unknown>)
-            : typeof raw === "string"
-              ? parseComposeArgString(raw)
-              : {}
-        return { ...base, _composeDocsDir: docs }
-      })
-
-    const run = Effect.fn("WorkflowTool.execute")(function* (
-      input: z.infer<typeof parameters>,
-      ctx: Tool.Context<Metadata>,
-    ) {
-      const runtime = yield* requireRuntime()
-
-      if (input.operation === "run") {
-        const cfg = yield* config.get()
-        // The schema keeps both `name` and `script` optional; enforce the xor
-        // here. Both-provided is a caller mistake (the schema docstring says
-        // "EITHER name OR script, not both") — fail loudly rather than silently
-        // picking one. Effect.orDie surfaces it to the model.
-        if (input.name && input.script) {
-          return yield* Effect.fail(
-            new Error("workflow run: provide either `name` (a built-in) or `script` (inline), not both."),
-          )
-        }
-        const script = input.name ? BuiltinWorkflow.get(input.name)?.script : input.script
-        if (!script) {
-          const known = BuiltinWorkflow.list()
-            .map((w) => w.name)
-            .join(", ")
-          return yield* Effect.fail(
-            new Error(
-              input.name
-                ? `Unknown built-in workflow "${input.name}". Known: ${known || "(none)"}.`
-                : "workflow run requires either `name` (a built-in) or `script` (inline).",
-            ),
-          )
-        }
-        const started = yield* runtime.start({
-          script,
-          sessionID: ctx.sessionID as SessionID,
-          parentActorID: ctx.agent ?? "main",
-          args: input.name === "compose" ? yield* enrichComposeArgs(input.args) : input.args,
-          workspace: input.workspace,
-          maxConcurrentAgents: cfg.workflow?.maxConcurrentAgents,
-          scriptDeadlineMs: cfg.workflow?.scriptDeadlineMs,
-          // Only the async (background) path relies on the inbox notification; the
-          // sync path below returns the result inline, so suppress the duplicate.
-          notifyOnTerminal: input.async === true,
-        })
-        const runID = started.runID
-        const label = input.name ?? "inline"
-
-        // Async opt-out: legacy fire-and-forget semantic. Returns the run_id
-        // immediately and lets the workflow keep running in the background; the
-        // terminal result arrives later as an inbox notification on the parent's
-        // next turn. Use this for very long workflows (deep-research, etc.) where
-        // blocking the agent's turn for the full duration is undesirable.
-        if (input.async === true) {
-          return {
-            title: "workflow started",
-            output: `Workflow started in background. run_id: ${runID}\nThe result will be delivered as a notification when complete.`,
-            metadata: { runID, status: "running" } satisfies Metadata,
-          }
-        }
-
-        // Default sync path: block until terminal so the model + user see phase
-        // and log() events as the tool's own message stream (skill-like) instead
-        // of a bare run_id followed by silence until the next turn drains the
-        // inbox. We read the transcript from the runtime's authoritative per-run
-        // buffer (populated synchronously by the guest hooks) rather than
-        // subscribing to the bus: that avoids the subscribe-after-start head race,
-        // cross-event reordering, the post-wait tail race, and any subscription
-        // leak on interrupt. The buffer flushes to part-state metadata as it grows
-        // — the TUI re-renders each delta via the existing message.part.delta path.
-        yield* ctx.metadata({
-          metadata: { runID, status: "running", transcript: [] } satisfies Metadata,
-        })
-
-        // A 250ms flush loop reads the runtime's transcript + live counters and
-        // pushes a CAPPED snapshot through ctx.metadata (reusing the per-part-state
-        // delta channel, so TUI consumers need no new subscription). The cap keeps
-        // each delta bounded regardless of event count. forkScoped binds the fiber to
-        // the execute scope below, so it is interrupted on completion OR interrupt.
-        // Counters are flushed alongside the transcript so the inline panel shows live
-        // ✓/✗/⟳ progress (they can change without a new transcript line — an agent can
-        // settle without a log() — so we flush on EITHER changing).
-        let lastLen = 0
-        let lastCounters = ""
-        const flushFiber = yield* Effect.forkScoped(
-          Effect.gen(function* () {
-            while (true) {
-              yield* Effect.sleep("250 millis")
-              const t = yield* runtime.transcript({ runID })
-              const s = yield* runtime.status({ runID })
-              const counters = { running: s.running, succeeded: s.succeeded, failed: s.failed }
-              const countersKey = `${counters.running}/${counters.succeeded}/${counters.failed}`
-              if (t.length === lastLen && countersKey === lastCounters) continue
-              lastLen = t.length
-              lastCounters = countersKey
-              yield* ctx.metadata({
-                metadata: {
-                  runID,
-                  status: "running",
-                  transcript: capTranscript(t),
-                  counters,
-                  ...(s.currentPhase !== undefined ? { currentPhase: s.currentPhase } : {}),
-                } satisfies Metadata,
-              })
-            }
-          }),
-        )
-
-        const outcome = yield* runtime.wait({ runID })
-        yield* Fiber.interrupt(flushFiber)
-
-        // Final counters/phase for the terminal metadata so the inline panel keeps
-        // showing the true ✓/✗/⟳ after the run ends (not the last mid-flush value).
-        const finalStatus = yield* runtime.status({ runID })
-        const finalCounters = {
-          running: finalStatus.running,
-          succeeded: finalStatus.succeeded,
-          failed: finalStatus.failed,
-        }
-        const finalPhase = finalStatus.currentPhase
-
-        // The guest hooks append synchronously and complete before the script
-        // returns (which resolves wait()), so this snapshot is the full, ordered
-        // transcript. Cap it for both the model-facing output and persisted metadata.
-        const finalTranscript = capTranscript(yield* runtime.transcript({ runID }))
-        const lines = finalTranscript.map((e) => (e.kind === "phase" ? `▸ ${e.text}` : `  ${e.text}`))
-        if (outcome.status === "completed") {
-          const result = JSON.stringify(outcome.result ?? null)
-          const truncated = result.length > 4000 ? result.slice(0, 4000) + " …(truncated)" : result
-          return {
-            title: `workflow ${label} completed`,
-            output:
-              (lines.length ? lines.join("\n") + "\n\n" : "") +
-              `Result: ${truncated}\nrun_id: ${runID}`,
-            metadata: {
-              runID,
-              status: "completed",
-              transcript: finalTranscript,
-              counters: finalCounters,
-              ...(finalPhase !== undefined ? { currentPhase: finalPhase } : {}),
-            } satisfies Metadata,
-          }
-        }
-        if (outcome.status === "failed") {
-          return {
-            title: `workflow ${label} failed`,
-            output:
-              (lines.length ? lines.join("\n") + "\n\n" : "") +
-              `Error: ${outcome.error}\nrun_id: ${runID}`,
-            metadata: {
-              runID,
-              status: "failed",
-              transcript: finalTranscript,
-              counters: finalCounters,
-              ...(finalPhase !== undefined ? { currentPhase: finalPhase } : {}),
-            } satisfies Metadata,
-          }
-        }
-        return {
-          title: `workflow ${label} cancelled`,
-          output:
-            (lines.length ? lines.join("\n") + "\n\n" : "") + `Cancelled.\nrun_id: ${runID}`,
-          metadata: {
-            runID,
-            status: "cancelled",
-            transcript: finalTranscript,
-            counters: finalCounters,
-            ...(finalPhase !== undefined ? { currentPhase: finalPhase } : {}),
-          } satisfies Metadata,
-        }
-      }
-      if (input.operation === "status") {
-        const snapshot = yield* runtime.status({ runID: input.run_id })
-        return {
-          title: `workflow ${snapshot.status}`,
-          output: JSON.stringify(snapshot),
-          metadata: { runID: input.run_id, status: snapshot.status } satisfies Metadata,
-        }
-      }
-      if (input.operation === "wait") {
-        const outcome = yield* runtime.wait({ runID: input.run_id, timeoutMs: input.timeout_ms })
-        return {
-          title: `workflow ${outcome.status}`,
-          output: JSON.stringify(outcome),
-          metadata: { runID: input.run_id, status: outcome.status } satisfies Metadata,
-        }
-      }
-      if (input.operation === "cancel") {
-        yield* runtime.cancel({ runID: input.run_id })
-        return {
-          title: "workflow cancelled",
-          output: `Cancelled ${input.run_id}`,
-          metadata: { runID: input.run_id, status: "cancelled" } satisfies Metadata,
-        }
-      }
-      if (input.operation === "resume") {
-        const resumed = yield* runtime.resume({ runID: input.run_id })
-        return {
-          title: resumed.resumed ? "workflow resumed" : "workflow not resumable",
-          output: JSON.stringify(resumed),
-          metadata: { runID: input.run_id } satisfies Metadata,
-        }
-      }
-      input satisfies never
-      throw new Error(`unhandled workflow operation: ${(input as { operation: string }).operation}`)
-    })
-
-    return {
-      description: DESCRIPTION,
-      parameters,
-      execute: (input: z.infer<typeof parameters>, ctx: Tool.Context<Metadata>) =>
-        run(input, ctx).pipe(Effect.scoped, Effect.orDie),
-    } satisfies Tool.DefWithoutID<typeof parameters, Metadata>
-  }),
-)

package/src/tool/workflow.txt

@@ -1,25 +0,0 @@
-Execute a workflow script that orchestrates multiple subagents deterministically. The script is plain JavaScript that runs in a sandbox and fans out subagents via agent(), parallel(), and pipeline(). The "run" operation BLOCKS until the workflow reaches a terminal status (completed/failed/cancelled) and returns the full transcript (phase transitions + log() messages) followed by the script's return value. Phase and log lines stream into the conversation as the workflow runs.
-
-operation "run": start a workflow and block until it terminates. Provide either `name` (a built-in workflow, see the catalog below) or `script` (inline JS; must begin with `export const meta = { name, description }`). Returns the transcript + result. Optionally provide `workspace` (a dir the script's file primitives are jailed to; defaults to the worktree). Note: long workflows (e.g. deep-research) hold the agent's turn for the full duration — that is intentional, mirroring skill semantics.
-operation "status": check a run's status by run_id.
-operation "wait": block until a run completes (or times out), returning its result.
-operation "cancel": cancel a running workflow by run_id (best-effort; in-flight subagents stop at their next safe point, not instantly).
-operation "resume": re-launch a persisted workflow by run_id under the same run_id (re-runs its script; a convergent script does less work the second time).
-
-Inside the script you can call:
-- agent(prompt, opts?) -> Promise: spawn one subagent; resolves to its result (a validated object if opts.schema given, else its final text) or null on failure. Never throws.
-- parallel(thunks) -> Promise<any[]>: run thunks concurrently; a thunk that throws resolves to null.
-- pipeline(items, ...stages) -> Promise<any[]>: run each item through all stages; no barrier between stages.
-- workflow(nameOrScript, args?, opts?) -> Promise: run a CHILD workflow as its own sub-run and await its result. nameOrScript is either an inline script (starts with `export const meta`) or a saved workflow name resolved from .opendash/workflows/ or .claude/workflows/. args is passed to the child as its `args`. opts: { workspace?, maxConcurrentAgents? }. A failed child resolves to null (never throws); an unknown name or a cycle/over-depth throws (fails the run). Children share the process-wide concurrency ceiling and inherit the parent workspace by default.
-- readFile(path) -> Promise<string|null>: read a file in the workspace (null if absent).
-- writeFile(path, content) -> Promise: write a file in the workspace (parent dirs auto-created).
-- glob(pattern) -> Promise<string[]>: list workspace paths matching the glob, sorted, files and dirs. Use this to enumerate work units — do NOT spawn an agent to list files.
-- exists(path) -> Promise<boolean>: whether a workspace path exists.
-- phase(title), log(message): progress reporting.
-- args: the JSON value passed when starting the workflow.
-
-Concurrency is capped by the host (default min(16, 2x cores)); excess agent() calls queue automatically.
-
-Communicate between workflows by dataflow: return a value from a child and pass it as args to the next (or write a shared file via writeFile and read it in a later phase). Workflows do not message each other directly. File primitives are jailed to the workspace root (the project worktree by default, or the `workspace` you pass to the run op) by a LEXICAL name check — it blocks `..` and absolute escapes, but does not resolve symlinks, so treat it as scoping, not a hard security boundary.
-
-workflow() cycle detection is asymmetric: a SAVED name is checked by name (so A calling A is a cycle regardless of args), while an INLINE script is checked by content+args (so an inline body that calls itself with DIFFERENT args is not flagged as a cycle and is bounded only by maxDepth). A cycle, over-maxDepth, or unknown name THROWS at the workflow() call site, which fails the run if uncaught — but a try/catch around workflow() in the guest will silence those throws, so don't wrap workflow() in try/catch unless you intend to ignore configuration bugs.