Skaile Workspaces

The @skaile/workspaces npm package — the full Skaile agent runtime stack as one published package. Every internal folder is exposed as a subpath export and the skaile CLI ships as its bin, alongside sibling packages for the binding / plugin surfaces.

Packages

| Subpath / Sibling | npm | What It Does | |---|---|---| | core | @skaile/workspaces/core | Shared types, manifest parsing, settings, store, framework config. Zero heavy deps. | | types | @skaile/workspaces/types | Unified message types, event types, and runtime interfaces. The shared contract. | | bridge | @skaile/workspaces/bridge | Pluggable agent driver abstraction. Backends: Claude SDK, Codex, OMP. | | flow engine | @skaile/workspaces/factory-assets/connectors/flow/engine | Flow state machine with typed bindings, precondition admission, consumed-output validation, deterministic routing, active strict v2 agent/function/gate/router/sub-flow nodes, and legacy skill compatibility. | | flow contract | @skaile/workspaces/factory-assets/connectors/flow/contract | Strict Flow v2 authoring schemas, v1 normalization, bounded expressions, binding origins, and canonical content identity. | | resolver | @skaile/workspaces/resolver | Parses SKILL.md requirements (reads_from, writes_to), validates gates, generates agent preamble. | | client | @skaile/workspaces/client | Framework-agnostic protocol client. Implements IAgentRuntime over a pluggable transport. | | transport | @skaile/workspaces/transport | Transport adapters (WebSocket client/server). Pluggable — add stdio, IPC, etc. | | connectors | @skaile/workspaces/connectors | Resource adapter infrastructure — unified access to git, postgres, redis, s3, sqlite, webdav, and more. | | session | @skaile/workspaces/session | Session message dispatcher — bridges frontend subscribers with agent clients through a persisted message stream. | | runner | @skaile/workspaces/runner | Headless agent runtime. Builds injected/native agent sessions, manages session state, executes flows via bridge. | | asset-manager | @skaile/workspaces/asset-manager | Programmatic asset management API. Catalog, install / remove, workspace scaffolder. | | cli | @skaile/workspaces (bin: skaile) | The skaile CLI binary — run skills, flows, manage projects. Also importable via the @skaile/workspaces/cli subpath. | | React bindings | @skaile/workspace-bridge-react | useAgentStore + useResourceClient for React 18+. Separate npm package, lives at packages/bridge-react in this monorepo. | | Vue bindings | @skaile/workspace-bridge-vue | useAgentStore + useResourceClient for Vue 3.3+. Separate npm package, lives at packages/bridge-vue in this monorepo. |

Coding-agent plugin integration is CLI-generated — run skaile plugin install --driver <claude-code|omp|codex>. There are no separate plugin packages.

Dependency Graph

cli  (top-level CLI — orchestrates everything below)
 │
 ├── runner          (headless runtime — session state, flow execution)
 │    ├── bridge     (pluggable LLM driver: Claude SDK, Codex, OMP)
 │    ├── transport  (WebSocket server transport for serve mode)
 │    ├── resolver   (skill requirements parsing + validation)
 │    ├── connectors (optional — external data backend access)
 │    └── core       (shared types, manifest parsing, store)
 │
 └── asset-manager   (asset management API + workspace scaffolder)
      └── core

types is consumed by bridge, client, transport, runner, cli, and the platform — it has no internal deps.

client + transport are consumed by the platform backend and any other agent consumer. Client depends only on types.

session wraps a client with persistence (MessageStore) and fan-out (SubscriberTransport). Consumed by the platform backend and forge apps. Depends on client + types.

core is the foundation — consumed by runner, asset-manager, cli, connectors, and ai-resource-manager.

How They Interact

1. User runs skaile run <flow> → cli parses args, resolves the flow file, and delegates to runner.

2. runner loads the flow through the shared v2 parser, then the flow engine computes which agent, function, gate, router, and sub-flow nodes are available from completed/skipped state, hard edges, and deterministic preconditions.

3. Router frontier waves settle before other runtime work, select each first matching route, and prune only hard-flow-exclusive losing paths without an executor or model. Function nodes run with resolved bindings in the existing session workspace, gate nodes park for a human decision, and sub-flow nodes delegate inline. For an agent node, the flow connector presents its interpolated instruction, resolved values and origins, reusable asset requirements, and predecessor context to the session agent.

4. bridge starts the LLM backend (Claude SDK or Codex in-process, or OMP as a subprocess) and streams AgentEvents (defined in types) back to the runner.

5. If the workspace has connectors declared (skaile.yaml connectors section), runner uses connectors to connect, mount, and inject tools before each flow execution.

6. asset-manager handles initial project setup (skaile init) — scaffolding directories, writing config files, and optionally building Docker images.

Quick Start

# From the monorepo root
bun run cli --help          # run the skaile CLI
bun run cli skill list      # list available skills
bun run cli run mvp         # run a flow

Flow authors and editor integrations can import the v2 contract independently:

import {
  FlowDefinitionSchema,
  parseFlowDefinition,
} from "@skaile/workspaces/factory-assets/connectors/flow/contract"

Flow Engine v2 defines seven node kinds: agent, subprompt, function, check, gate, router, and inline sub-flow. It rejects unknown v2 keys with precise paths, and normalizes recognized v1 definitions deterministically. Exact legacy sub-flow nodes now activate, while every other legacy kind retains its existing compatibility state trace. Structured output references are checked against declared producer fields, and gates carry a strict response schema. The generated schema is published as both contract/flow.v2.schema.json and contract/schema.json. Explicit legacy type: skill and exact type: sub-flow nodes normalize to their executable v2 kinds; every other legacy kind remains an inert compatibility placeholder with its IDs, parameters, assets, and dependency semantics retained. The runtime activates all seven kinds: agent, subprompt, function, check, gate, router, and sub-flow. Interpolated agent instructions, resolved values, and origins reach the session agent through build_handoff(nodeId); function and check nodes run shell, Node, or Python commands in the existing session workspace without a model turn, with resolved values exported as environment variables — a check's exit status is a pass/fail verdict rather than a plain success/failure. Subprompt nodes are function-shaped except for how the work runs: a second, isolated AgentDriver instance per call, with no Skaile system prompt, no MCP servers, no connector capabilities, and no access to the session conversation, bounded to a single turn. It does retain the backend's own native tool surface (a coding backend keeps its file and shell tools, rooted at the session workspace) — isolation here means a separate conversation, not a sandbox, resolving its declared run.model tier via a pure resolveModelTier against per-provider built-in tiers, failing the node rather than substituting a model when a tier cannot be served. A declared output contract drives a JSON-response request and response parsing through the same consumed-output validation every kind uses; there is no corrective reprompt, so a parse or validation failure is an ordinary node failure. A subprompt's output is classified agent-obtained, so a downstream check always derives "asserted" provenance over it, never "verified". That classification is transitive — every executed node persists the origins it resolved on NodeExecution.inputOrigins, so a deterministic node that carries an agent's value forward cannot launder it to runtime-obtained, and a producer with no persisted origins (a run predating the field) is read as agent-obtained rather than clean. Gate nodes park immediately through the durable approval state, complete on approval, and preserve rejection feedback for revision and a later approval re-request. Router nodes evaluate ordered bounded expressions only after admission. The first matching route wins; coordinated choices are retained across hydration, and only hard-flow-exclusive losing paths are skipped while shared or externally live convergence stays available. An unfinished declared output waits without starving unrelated runtime work; possible branch targets stay off runtime and agent availability until selection. Routers never invoke the session agent, model client, or NodeExecutor. Sub-flow nodes load one child inline through the same session, driver, NodeExecutor, gate operations, and FlowAdapter lifecycle. Parked approval and input interactions are published on the parent sub-flow node, while the child adapter remains transient and resumable in memory. Canonical flow identities, cycle detection, and a depth bound keep resolution contained. Sub-flows create no run group, loop behavior, second executor, child record, or new durable-state field. Downstream-consumed output schemas are enforced at completion. Agents receive one durable corrective call; deterministic functions fail directly. Unconsumed schemas remain prose-only. Skills, connectors, mounts, MCP servers, and knowledge stay reusable run.assets requirements, and shared refs are deduplicated in the dependency graph. All seven current kinds — agent, subprompt, function, check, gate, router, and sub-flow — are active. FlowDefinition is the strict authored-v2 type; parser results use the wider ParsedFlowDefinition so unknown legacy edge kinds and their metadata can be retained inertly without weakening authored validation. See the Flow v2 authoring contract for the complete shape, evaluator bounds, generated JSON Schema, and content hash.

Architecture Docs

• Client-Server Architecture — design for the agent client, transport, and shared state protocol (new packages: client, transport)
• Session Dispatcher Architecture — design for session message dispatching, persistence, and fan-out (new package: session)

See each package's CLAUDE.md for architecture details and developer conventions.