@cybernetyx1/atlasflow-runtime

The portable TypeScript runtime and SDK used inside AtlasFlow agent code — define agents, tools, channels, commands, and durable runs.

Install

npm install @cybernetyx1/atlasflow-runtime

Part of the AtlasFlow monorepo. Proprietary.

Usage

Define a tool with defineTool, then build an agent with defineAgent / createAgent. Channels (defineChannel) receive inbound events, commands (defineCommand) expose callable operations, and invokeAgent runs an agent durably.

Tool parameters are described once as a Valibot schema; the runtime infers the JSON Schema the model needs.

import { defineTool, defineAgent } from "@cybernetyx1/atlasflow-runtime";
import * as v from "valibot";

const addTool = defineTool({
  name: "add",
  description: "Add two numbers",
  parameters: v.object({ a: v.number(), b: v.number() }),
  execute({ a, b }) {
    return String(a + b);
  },
});

export const agent = defineAgent({
  name: "calculator",
  instructions: "You add numbers using the add tool.",
  tools: [addTool],
});

import { defineChannel, verifySlackRequestSignature } from "@cybernetyx1/atlasflow-runtime";

export const slackChannel = defineChannel({
  name: "slack",
  async handle(ctx) {
    const body = await ctx.text();
    // verify the signature, then return a dispatch describing the run to start
    return { continuationToken: "thread-1", agent: "calculator", message: body };
  },
});

Other primary entry points: defineAgentProfile, defineCommand, defineMemoryConnector, defineHttpConnection, defineSandbox, defineEval, personaAgent / parsePersonaManifest (persona compile target), startWorkflow / advanceWorkflow (authored workflows), invokeAgent / dispatchWorkflow / recoverRuns, builtinTools, connectMcpServer, observe / EventBus (events), and persistence adapters (inMemoryAdapter, kvAdapter). See src/index.ts for the full surface.

Run dispatch admission

POST /runs, POST /runs/:name, and the deprecated POST /workflows/:name alias accept Idempotency-Key. The key must contain 1-256 UTF-8 bytes and is scoped to the deployment's persistence store. The first request atomically admits one run. A retry with the same normalized execution input returns the same run id without executing again; the same key with different input returns 409 idempotency_conflict. Omitting the header preserves fresh-run behavior.

Payload identity is SHA-256 over canonical JSON. It includes the resolved run kind and name; agent input includes normalized message, payload, and images, while workflow input includes payload. Object keys are sorted, array order is preserved, and response-only wait controls are excluded. The raw idempotency key is not persisted—only its SHA-256 hash is stored with the run record.

Replay responses project the current durable run record rather than reproduce the original HTTP response body. A completed wait-mode replay returns the one persisted result value as data when it is a string or result otherwise, and does not include non-persisted usage. A wait-mode replay of an in-flight run returns 202 with its current queued, running, or waiting_approval status instead of attaching to the existing execution.

ATLASFLOW_API_KEY remains the primary bearer for every authenticated route. Set ATLASFLOW_DISPATCH_KEY to allow a scheduler or control plane to call only the three dispatch routes above. That credential is rejected by sessions, run/event reads, approvals, streams, and admin routes. A dispatch-key-only client therefore needs the primary key or a scoped token to poll GET /runs/:id.

Run completion export

RunCompletedV1 is the versioned, runtime-owned contract for exporting terminal run evidence to a managed control plane. Generated deployments enable the durable reconciler when ATLASFLOW_RUN_COMPLETION_URL and ATLASFLOW_RUN_COMPLETION_TOKEN are configured. Node requires Postgres; Cloudflare requires the Durable Object runtime. Receivers must durably deduplicate Idempotency-Key within the authenticated deployment principal before returning success. Managed deployments set ATLASFLOW_RELEASE_ID; the runtime snapshots it on run admission and exports it as immutable release provenance, so delayed delivery remains correct across redeploys. The wire contract is capped at 256 KiB. Oversized events and deterministic contract rejections are retained as dead-lettered outbox evidence instead of being retried forever.

License

Proprietary. © 2026 Cybernetyx. See LICENSE.