@relayflows/surface 2.0.0

package/README.md

@@ -0,0 +1,62 @@
+# `@relayflows/surface`
+
+The TypeScript authoring contract described by `docs/SURFACE.md`.
+
+The package defines flows and the context that a future journal-backed runtime
+will inject. A flow handle retains an immutable header and body behind the
+`@relayflows/surface/runtime` bridge used by in-repository SDK inspection; the
+public handle remains the frozen `{ name }` authoring value. This package never
+constructs a context, executes a body, or contacts the kernel. The SDK has an
+internal test seam proving an awaited plain `f.run(...)` can cross the existing
+journal protocol, but it is intentionally not exported as a runner: authored
+body progress does not yet have a durable root journal or crash-safe resume.
+Within that seam, a root operation must participate in the asynchronous
+continuation that reaches `done()`. Direct `await` is supported, including steps
+constructed before they are awaited, and so are awaited `Promise.resolve`,
+`Promise.all`, `Promise.allSettled`, `Promise.any` and `Promise.race`. Ignored
+operations, manual `.then` callbacks, ignored combinators, callback failures that
+are caught away, and derived work still in flight when the body returns are all
+refused before the terminal journal step; callback source text is never treated
+as lifecycle proof.
+
+Note that executing an authored body replaces the global `Promise.all` for the
+duration of the run. The reason, the scope, and the one documented limit of the
+lifecycle contract are in `docs/SURFACE.md`, "The authored operation lifecycle".
+
+This is an in-repository foundation, not a registry-published package. The
+repository's `flows run` command can execute a directly authored `.flow.ts`
+with required JSON input. Durable authored-root resume remains tracked in issue
+#132. Resident trigger handlers (`flow.on(...)`) are gate-2 work and are not yet
+part of this package.
+
+The repository pins Bun through `surface/bun.lock`. From a fresh checkout:
+
+```sh
+cd surface
+bun install --frozen-lockfile --ignore-scripts
+bun run build
+bun run test
+```
+
+```ts
+import { flow } from "@relayflows/surface";
+
+export default flow<{ base: string }>("release-note", {}, async (f, input) => {
+  await f.run(`git diff ${input.base}`);
+  f.done("success");
+});
+```
+
+Run it with inline JSON or the path to a JSON file:
+
+```sh
+flows run release-note.flow.ts --input '{"base":"main"}'
+flows run release-note.flow.ts --input ./release-note.input.json
+```
+
+Direct input is limited to 1,048,576 UTF-8 bytes. Missing, invalid, or
+oversized input is refused before the daemon is contacted.
+
+Direct runs use the same journal-backed executor as other authored flows, so
+branches over step output observe the value recorded by `step.completed`.
+Unsupported headers, verbs, and code predicate gates fail closed.

package/dist/cloud.d.ts

@@ -0,0 +1,92 @@
+import type { Step } from "./step.js";
+import type { CompletionReason, RunCompletionReason } from "./completion.js";
+export interface WorkerSummary {
+    workerId: string;
+    status: string;
+    lastSeenAt: string | null;
+}
+export interface Heartbeat extends WorkerSummary {
+}
+export interface EnrollmentReceipt {
+    /** Mount path for the token. The credential itself never enters the journal. */
+    tokenPath: string;
+    expiresAt: string;
+    registerCommand: string;
+}
+export interface ScheduleState {
+    id: string;
+    lastTriggerStatus: string | null;
+    lastTriggeredRunId: string | null;
+    lastTriggerError: string | null;
+}
+export interface JournalStep {
+    id: string;
+    type: "deterministic" | "llm" | "agent";
+    completionReason: CompletionReason | null;
+}
+export interface RunJournal {
+    runId: string;
+    steps: JournalStep[];
+    completionReason: RunCompletionReason | null;
+}
+/** AgentWorkforce Cloud helper contract generated from its relayfile adapter. */
+export interface CloudHelper {
+    workers: {
+        mintEnrollmentToken(input: {
+            workspaceId: string;
+            name: string;
+            /** Principal resolved at `<mount>/principals/<as>`. */
+            as: string;
+        }): Step<EnrollmentReceipt>;
+        list(input: {
+            workspaceId: string;
+            as: string;
+        }): Step<{
+            online: WorkerSummary[];
+            all: WorkerSummary[];
+        }>;
+        heartbeat(input: {
+            workerId: string;
+            as: string;
+        }): Step<Heartbeat>;
+        awaitHeartbeat(input: {
+            workerId: string;
+            as: string;
+            within: string;
+        }): Step<Heartbeat>;
+    };
+    schedules: {
+        create(input: {
+            workspaceId: string;
+            workflow: string;
+            cron: string;
+            name: string;
+            as: string;
+        }): Step<{
+            id: string;
+        }>;
+        fire(input: {
+            scheduleId: string;
+            as: string;
+        }): Step<{
+            accepted: boolean;
+        }>;
+        get(input: {
+            scheduleId: string;
+            as: string;
+        }): Step<ScheduleState>;
+        remove(input: {
+            scheduleId: string;
+            as: string;
+        }): Step<{
+            deleted: boolean;
+        }>;
+    };
+    runs: {
+        journal(input: {
+            runId: string;
+            as: string;
+        }): Step<RunJournal>;
+    };
+}
+//# sourceMappingURL=cloud.d.ts.map

package/dist/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"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"}

package/dist/cloud.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cloud.js.map

package/dist/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":""}

package/dist/completion.d.ts

@@ -0,0 +1,7 @@
+/** The closed step completion vocabulary from the journal protocol. */
+export declare const COMPLETION_REASONS: readonly ["success", "verification_failed", "retries_exhausted", "lease_expired", "crashed", "timeout", "worker_error", "budget_exceeded", "canceled"];
+export type CompletionReason = (typeof COMPLETION_REASONS)[number];
+/** The closed run completion vocabulary from the journal protocol. */
+export declare const RUN_COMPLETION_REASONS: readonly ["success", "step_failed", "canceled", "budget_exceeded"];
+export type RunCompletionReason = (typeof RUN_COMPLETION_REASONS)[number];
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,wJAUrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,oEAKzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/completion.js

@@ -0,0 +1,20 @@
+/** The closed step completion vocabulary from the journal protocol. */
+export const COMPLETION_REASONS = [
+    "success",
+    "verification_failed",
+    "retries_exhausted",
+    "lease_expired",
+    "crashed",
+    "timeout",
+    "worker_error",
+    "budget_exceeded",
+    "canceled",
+];
+/** The closed run completion vocabulary from the journal protocol. */
+export const RUN_COMPLETION_REASONS = [
+    "success",
+    "step_failed",
+    "canceled",
+    "budget_exceeded",
+];
+//# sourceMappingURL=completion.js.map

package/dist/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,qBAAqB;IACrB,mBAAmB;IACnB,eAAe;IACf,SAAS;IACT,SAAS;IACT,cAAc;IACd,iBAAiB;IACjB,UAAU;CACF,CAAC;AAIX,sEAAsE;AACtE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,aAAa;IACb,UAAU;IACV,iBAAiB;CACT,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,29 @@
+import type { CloudHelper } from "./cloud.js";
+import type { RunCompletionReason } from "./completion.js";
+import type { Step } from "./step.js";
+export interface AgentResult {
+    summary: string;
+    artifacts: string[];
+}
+export interface AgentOptions {
+    task: string;
+    workspace?: string;
+}
+/**
+ * The context a journal-backed runtime injects into a flow body.
+ *
+ * This package declares the authoring contract only. It cannot construct a
+ * context or execute a step, so all effects remain behind the journal client.
+ */
+export interface Ctx {
+    run(command: string): Step<string>;
+    llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
+    agent(name: string, options: AgentOptions): Step<AgentResult>;
+    human(question: string, options: {
+        to: string;
+    }): Promise<boolean>;
+    dispatch<T>(flow: string, input: unknown): Promise<T>;
+    done(reason: RunCompletionReason): void;
+    cloud: CloudHelper;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,GAAG;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9D,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxC,KAAK,EAAE,WAAW,CAAC;CACpB"}

package/dist/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":""}

package/dist/flow.d.ts

@@ -0,0 +1,47 @@
+import type { Ctx } from "./context.js";
+/** Optional escalation header; the empty header is the common case. */
+export interface FlowHeader {
+    identity?: string;
+    memory?: {
+        script?: boolean;
+        agent?: boolean;
+    };
+    budget?: string;
+    tools?: {
+        relayfile?: string[];
+        mcp?: string[];
+    };
+    workspace?: string;
+}
+export type FlowBody<Input = unknown> = (f: Ctx, input: Input) => Promise<void>;
+export interface ReadonlyFlowHeader {
+    readonly identity?: string;
+    readonly memory?: Readonly<{
+        script?: boolean;
+        agent?: boolean;
+    }>;
+    readonly budget?: string;
+    readonly tools?: Readonly<{
+        relayfile?: readonly string[];
+        mcp?: readonly string[];
+    }>;
+    readonly workspace?: string;
+}
+/** Immutable definition retained for the SDK's journal-backed runtime. */
+export interface AuthoredFlowDefinition<Input = unknown> {
+    readonly name: string;
+    readonly header: ReadonlyFlowHeader;
+    readonly body: FlowBody<Input>;
+}
+/** Opaque authored-flow handle. Execution stays behind the journal runtime. */
+export interface FlowHandle {
+    readonly name: string;
+}
+export declare function flow<Input = unknown>(name: string, body: FlowBody<Input>): FlowHandle;
+export declare function flow<Input = unknown>(name: string, header: FlowHeader, body: FlowBody<Input>): FlowHandle;
+/**
+ * Runtime bridge used by the SDK after it imports an authored `.flow.ts`.
+ * The root package deliberately does not re-export this accessor.
+ */
+export declare function getFlowDefinition<Input = unknown>(handle: FlowHandle): AuthoredFlowDefinition<Input>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,QAAQ,CAAC,KAAK,GAAG,OAAO,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;QACxB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC9B,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;CAChC;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC;AACvF,wBAAgB,IAAI,CAAC,KAAK,GAAG,OAAO,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,GACpB,UAAU,CAAC;AAkCd;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAapG"}

package/dist/flow.js

@@ -0,0 +1,148 @@
+const definitions = new WeakMap();
+export function flow(name, headerOrBody, body) {
+    const flowBody = typeof headerOrBody === "function" ? headerOrBody : body;
+    const header = typeof headerOrBody === "function" ? {} : headerOrBody;
+    if (name.trim().length === 0) {
+        throw new TypeError("flow name must not be empty");
+    }
+    if (typeof flowBody !== "function") {
+        throw new TypeError(`flow "${name}" requires a body`);
+    }
+    assertFlowHeader(header, name);
+    const definition = Object.freeze({
+        name,
+        header: freezeHeader(header),
+        body: flowBody,
+    });
+    const handle = Object.freeze({ name });
+    // One map holds definitions of many input types, so it is stored at the
+    // default parameterisation and `getFlowDefinition<Input>` re-parameterises on
+    // the way out. The cast is needed because `body` puts `Input` in a parameter
+    // position, making the type invariant: `AuthoredFlowDefinition<Input>` is not
+    // assignable to `AuthoredFlowDefinition<unknown>` even though every read
+    // recovers the author's own type. Sound here because the handle-to-definition
+    // pairing is 1:1 and both sides are keyed by the same authored flow.
+    definitions.set(handle, definition);
+    return handle;
+}
+/**
+ * Runtime bridge used by the SDK after it imports an authored `.flow.ts`.
+ * The root package deliberately does not re-export this accessor.
+ */
+export function getFlowDefinition(handle) {
+    if ((typeof handle !== "object" && typeof handle !== "function") || handle === null) {
+        throw new TypeError("expected an @relayflows/surface flow handle");
+    }
+    const definition = definitions.get(handle);
+    if (definition === undefined
+        || !isStoredDefinition(definition, definition.name)
+        || handle.name !== definition.name) {
+        throw new TypeError("expected an @relayflows/surface flow handle");
+    }
+    return definition;
+}
+function isStoredDefinition(value, handleName) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof handleName === "string"
+        && candidate.name === handleName
+        && typeof candidate.body === "function"
+        && typeof candidate.header === "object"
+        && candidate.header !== null
+        && !Array.isArray(candidate.header)
+        && Object.isFrozen(candidate.header)
+        && Object.isFrozen(value);
+}
+function freezeHeader(header) {
+    const unknownFields = Object.keys(header).filter((field) => ![
+        "identity",
+        "memory",
+        "budget",
+        "tools",
+        "workspace",
+    ].includes(field));
+    if (unknownFields.length > 0) {
+        throw new TypeError(`flow header has unknown fields: ${unknownFields.join(", ")}`);
+    }
+    const memory = header.memory === undefined
+        ? undefined
+        : Object.freeze({ ...header.memory });
+    const tools = header.tools === undefined
+        ? undefined
+        : Object.freeze({
+            ...(header.tools.relayfile === undefined
+                ? {}
+                : { relayfile: Object.freeze([...header.tools.relayfile]) }),
+            ...(header.tools.mcp === undefined
+                ? {}
+                : { mcp: Object.freeze([...header.tools.mcp]) }),
+        });
+    return Object.freeze({
+        ...(header.identity === undefined ? {} : { identity: header.identity }),
+        ...(memory === undefined ? {} : { memory }),
+        ...(header.budget === undefined ? {} : { budget: header.budget }),
+        ...(tools === undefined ? {} : { tools }),
+        ...(header.workspace === undefined ? {} : { workspace: header.workspace }),
+    });
+}
+function assertFlowHeader(value, flowName) {
+    const at = `unsupported_header: flow "${flowName}" header`;
+    assertHeaderObject(value, at);
+    assertKnownKeys(value, ["identity", "memory", "budget", "tools", "workspace"], at);
+    assertOptionalString(value, "identity", at);
+    assertOptionalString(value, "budget", at);
+    assertOptionalString(value, "workspace", at);
+    if (value.memory !== undefined) {
+        assertHeaderObject(value.memory, `${at}.memory`);
+        assertKnownKeys(value.memory, ["script", "agent"], `${at}.memory`);
+        assertOptionalBoolean(value.memory, "script", `${at}.memory`);
+        assertOptionalBoolean(value.memory, "agent", `${at}.memory`);
+    }
+    if (value.tools !== undefined) {
+        assertHeaderObject(value.tools, `${at}.tools`);
+        assertKnownKeys(value.tools, ["relayfile", "mcp"], `${at}.tools`);
+        assertOptionalStringArray(value.tools, "relayfile", `${at}.tools`);
+        assertOptionalStringArray(value.tools, "mcp", `${at}.tools`);
+    }
+}
+function assertHeaderObject(value, at) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${at}: expected an object`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError(`${at}: expected a plain object`);
+    }
+}
+function assertKnownKeys(value, allowed, at) {
+    const allowedKeys = new Set(allowed);
+    for (const key of Reflect.ownKeys(value)) {
+        if (!allowedKeys.has(key)) {
+            throw new TypeError(`${at}: unknown field ${JSON.stringify(String(key))}`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !('value' in descriptor)) {
+            throw new TypeError(`${at}.${String(key)}: expected a data property`);
+        }
+    }
+}
+function assertOptionalString(value, key, at) {
+    if (value[key] !== undefined && typeof value[key] !== "string") {
+        throw new TypeError(`${at}.${key}: expected a string`);
+    }
+}
+function assertOptionalBoolean(value, key, at) {
+    if (value[key] !== undefined && typeof value[key] !== "boolean") {
+        throw new TypeError(`${at}.${key}: expected a boolean`);
+    }
+}
+function assertOptionalStringArray(value, key, at) {
+    const candidate = value[key];
+    if (candidate !== undefined
+        && (!Array.isArray(candidate) || candidate.some((item) => typeof item !== "string"))) {
+        throw new TypeError(`${at}.${key}: expected an array of strings`);
+    }
+}
+//# sourceMappingURL=flow.js.map

package/dist/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { EnrollmentReceipt, Heartbeat, JournalStep, RunJournal, ScheduleState, WorkerSummary, CloudHelper, } from "./cloud.js";
+export type { AgentOptions, AgentResult, Ctx } from "./context.js";
+export { COMPLETION_REASONS, RUN_COMPLETION_REASONS, type CompletionReason, type RunCompletionReason, } from "./completion.js";
+export type { Step } from "./step.js";
+export { flow, type FlowHandle, type FlowHeader, } from "./flow.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { COMPLETION_REASONS, RUN_COMPLETION_REASONS, } from "./completion.js";
+export { flow, } from "./flow.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GAGvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,IAAI,GAGL,MAAM,WAAW,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,2 @@
+export { getFlowDefinition, type AuthoredFlowDefinition, type FlowBody, type FlowHandle, type ReadonlyFlowHeader, } from "./flow.js";
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+export { getFlowDefinition, } from "./flow.js";
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAKlB,MAAM,WAAW,CAAC"}

package/dist/step.d.ts

@@ -0,0 +1,6 @@
+/** A journal-backed step result with its postfix verification gate. */
+export interface Step<T> extends PromiseLike<T> {
+    /** Fail the step with `verification_failed` when the predicate is false. */
+    gate(predicate: (value: T) => boolean, because?: string): Step<T>;
+}
+//# sourceMappingURL=step.d.ts.map

package/dist/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../src/step.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;CACnE"}

package/dist/step.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=step.js.map

package/dist/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../src/step.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@relayflows/surface",
+  "version": "2.0.0",
+  "description": "TypeScript authoring surface for Relayflows.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "typecheck:regressions": "tsc -p ../../regressions/tsconfig.json",
+    "test": "bun run build && tsc -p tsconfig.test.json && vitest run"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/flows.git",
+    "directory": "packages/surface"
+  }
+}

package/src/cloud.ts

@@ -0,0 +1,76 @@
+import type { Step } from "./step.js";
+import type {
+  CompletionReason,
+  RunCompletionReason,
+} from "./completion.js";
+
+export interface WorkerSummary {
+  workerId: string;
+  status: string;
+  lastSeenAt: string | null;
+}
+
+export interface Heartbeat extends WorkerSummary {}
+
+export interface EnrollmentReceipt {
+  /** Mount path for the token. The credential itself never enters the journal. */
+  tokenPath: string;
+  expiresAt: string;
+  registerCommand: string;
+}
+
+export interface ScheduleState {
+  id: string;
+  lastTriggerStatus: string | null;
+  lastTriggeredRunId: string | null;
+  lastTriggerError: string | null;
+}
+
+export interface JournalStep {
+  id: string;
+  type: "deterministic" | "llm" | "agent";
+  completionReason: CompletionReason | null;
+}
+
+export interface RunJournal {
+  runId: string;
+  steps: JournalStep[];
+  completionReason: RunCompletionReason | null;
+}
+
+/** AgentWorkforce Cloud helper contract generated from its relayfile adapter. */
+export interface CloudHelper {
+  workers: {
+    mintEnrollmentToken(input: {
+      workspaceId: string;
+      name: string;
+      /** Principal resolved at `<mount>/principals/<as>`. */
+      as: string;
+    }): Step<EnrollmentReceipt>;
+    list(input: { workspaceId: string; as: string }): Step<{
+      online: WorkerSummary[];
+      all: WorkerSummary[];
+    }>;
+    heartbeat(input: { workerId: string; as: string }): Step<Heartbeat>;
+    awaitHeartbeat(input: {
+      workerId: string;
+      as: string;
+      within: string;
+    }): Step<Heartbeat>;
+  };
+  schedules: {
+    create(input: {
+      workspaceId: string;
+      workflow: string;
+      cron: string;
+      name: string;
+      as: string;
+    }): Step<{ id: string }>;
+    fire(input: { scheduleId: string; as: string }): Step<{ accepted: boolean }>;
+    get(input: { scheduleId: string; as: string }): Step<ScheduleState>;
+    remove(input: { scheduleId: string; as: string }): Step<{ deleted: boolean }>;
+  };
+  runs: {
+    journal(input: { runId: string; as: string }): Step<RunJournal>;
+  };
+}

package/src/completion.ts

@@ -0,0 +1,24 @@
+/** The closed step completion vocabulary from the journal protocol. */
+export const COMPLETION_REASONS = [
+  "success",
+  "verification_failed",
+  "retries_exhausted",
+  "lease_expired",
+  "crashed",
+  "timeout",
+  "worker_error",
+  "budget_exceeded",
+  "canceled",
+] as const;
+
+export type CompletionReason = (typeof COMPLETION_REASONS)[number];
+
+/** The closed run completion vocabulary from the journal protocol. */
+export const RUN_COMPLETION_REASONS = [
+  "success",
+  "step_failed",
+  "canceled",
+  "budget_exceeded",
+] as const;
+
+export type RunCompletionReason = (typeof RUN_COMPLETION_REASONS)[number];

package/src/context.ts

@@ -0,0 +1,29 @@
+import type { CloudHelper } from "./cloud.js";
+import type { RunCompletionReason } from "./completion.js";
+import type { Step } from "./step.js";
+
+export interface AgentResult {
+  summary: string;
+  artifacts: string[];
+}
+
+export interface AgentOptions {
+  task: string;
+  workspace?: string;
+}
+
+/**
+ * The context a journal-backed runtime injects into a flow body.
+ *
+ * This package declares the authoring contract only. It cannot construct a
+ * context or execute a step, so all effects remain behind the journal client.
+ */
+export interface Ctx {
+  run(command: string): Step<string>;
+  llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
+  agent(name: string, options: AgentOptions): Step<AgentResult>;
+  human(question: string, options: { to: string }): Promise<boolean>;
+  dispatch<T>(flow: string, input: unknown): Promise<T>;
+  done(reason: RunCompletionReason): void;
+  cloud: CloudHelper;
+}

package/src/flow.ts

@@ -0,0 +1,245 @@
+import type { Ctx } from "./context.js";
+
+/** Optional escalation header; the empty header is the common case. */
+export interface FlowHeader {
+  identity?: string;
+  memory?: { script?: boolean; agent?: boolean };
+  budget?: string;
+  tools?: { relayfile?: string[]; mcp?: string[] };
+  workspace?: string;
+}
+
+export type FlowBody<Input = unknown> = (f: Ctx, input: Input) => Promise<void>;
+
+export interface ReadonlyFlowHeader {
+  readonly identity?: string;
+  readonly memory?: Readonly<{ script?: boolean; agent?: boolean }>;
+  readonly budget?: string;
+  readonly tools?: Readonly<{
+    relayfile?: readonly string[];
+    mcp?: readonly string[];
+  }>;
+  readonly workspace?: string;
+}
+
+/** Immutable definition retained for the SDK's journal-backed runtime. */
+export interface AuthoredFlowDefinition<Input = unknown> {
+  readonly name: string;
+  readonly header: ReadonlyFlowHeader;
+  readonly body: FlowBody<Input>;
+}
+
+/** Opaque authored-flow handle. Execution stays behind the journal runtime. */
+export interface FlowHandle {
+  readonly name: string;
+}
+
+const definitions = new WeakMap<object, AuthoredFlowDefinition>();
+
+export function flow<Input = unknown>(name: string, body: FlowBody<Input>): FlowHandle;
+export function flow<Input = unknown>(
+  name: string,
+  header: FlowHeader,
+  body: FlowBody<Input>,
+): FlowHandle;
+export function flow<Input = unknown>(
+  name: string,
+  headerOrBody: FlowHeader | FlowBody<Input>,
+  body?: FlowBody<Input>,
+): FlowHandle {
+  const flowBody = typeof headerOrBody === "function" ? headerOrBody : body;
+  const header = typeof headerOrBody === "function" ? {} : headerOrBody;
+
+  if (name.trim().length === 0) {
+    throw new TypeError("flow name must not be empty");
+  }
+  if (typeof flowBody !== "function") {
+    throw new TypeError(`flow "${name}" requires a body`);
+  }
+  assertFlowHeader(header, name);
+
+  const definition: AuthoredFlowDefinition<Input> = Object.freeze({
+    name,
+    header: freezeHeader(header),
+    body: flowBody,
+  });
+  const handle: FlowHandle = Object.freeze({ name });
+  // One map holds definitions of many input types, so it is stored at the
+  // default parameterisation and `getFlowDefinition<Input>` re-parameterises on
+  // the way out. The cast is needed because `body` puts `Input` in a parameter
+  // position, making the type invariant: `AuthoredFlowDefinition<Input>` is not
+  // assignable to `AuthoredFlowDefinition<unknown>` even though every read
+  // recovers the author's own type. Sound here because the handle-to-definition
+  // pairing is 1:1 and both sides are keyed by the same authored flow.
+  definitions.set(handle, definition as AuthoredFlowDefinition);
+  return handle;
+}
+
+/**
+ * Runtime bridge used by the SDK after it imports an authored `.flow.ts`.
+ * The root package deliberately does not re-export this accessor.
+ */
+export function getFlowDefinition<Input = unknown>(handle: FlowHandle): AuthoredFlowDefinition<Input> {
+  if ((typeof handle !== "object" && typeof handle !== "function") || handle === null) {
+    throw new TypeError("expected an @relayflows/surface flow handle");
+  }
+  const definition = definitions.get(handle);
+  if (
+    definition === undefined
+    || !isStoredDefinition(definition, definition.name)
+    || handle.name !== definition.name
+  ) {
+    throw new TypeError("expected an @relayflows/surface flow handle");
+  }
+  return definition;
+}
+
+function isStoredDefinition(
+  value: unknown,
+  handleName: unknown,
+): value is AuthoredFlowDefinition {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value as Partial<AuthoredFlowDefinition>;
+  return typeof handleName === "string"
+    && candidate.name === handleName
+    && typeof candidate.body === "function"
+    && typeof candidate.header === "object"
+    && candidate.header !== null
+    && !Array.isArray(candidate.header)
+    && Object.isFrozen(candidate.header)
+    && Object.isFrozen(value);
+}
+
+function freezeHeader(header: FlowHeader): ReadonlyFlowHeader {
+  const unknownFields = Object.keys(header).filter((field) => ![
+    "identity",
+    "memory",
+    "budget",
+    "tools",
+    "workspace",
+  ].includes(field));
+  if (unknownFields.length > 0) {
+    throw new TypeError(`flow header has unknown fields: ${unknownFields.join(", ")}`);
+  }
+  const memory = header.memory === undefined
+    ? undefined
+    : Object.freeze({ ...header.memory });
+  const tools = header.tools === undefined
+    ? undefined
+    : Object.freeze({
+        ...(header.tools.relayfile === undefined
+          ? {}
+          : { relayfile: Object.freeze([...header.tools.relayfile]) }),
+        ...(header.tools.mcp === undefined
+          ? {}
+          : { mcp: Object.freeze([...header.tools.mcp]) }),
+      });
+  return Object.freeze({
+    ...(header.identity === undefined ? {} : { identity: header.identity }),
+    ...(memory === undefined ? {} : { memory }),
+    ...(header.budget === undefined ? {} : { budget: header.budget }),
+    ...(tools === undefined ? {} : { tools }),
+    ...(header.workspace === undefined ? {} : { workspace: header.workspace }),
+  });
+}
+
+function assertFlowHeader(value: unknown, flowName: string): asserts value is FlowHeader {
+  const at = `unsupported_header: flow "${flowName}" header`;
+  assertHeaderObject(value, at);
+  assertKnownKeys(
+    value,
+    ["identity", "memory", "budget", "tools", "workspace"],
+    at,
+  );
+  assertOptionalString(value, "identity", at);
+  assertOptionalString(value, "budget", at);
+  assertOptionalString(value, "workspace", at);
+
+  if (value.memory !== undefined) {
+    assertHeaderObject(value.memory, `${at}.memory`);
+    assertKnownKeys(
+      value.memory,
+      ["script", "agent"],
+      `${at}.memory`,
+    );
+    assertOptionalBoolean(value.memory, "script", `${at}.memory`);
+    assertOptionalBoolean(value.memory, "agent", `${at}.memory`);
+  }
+
+  if (value.tools !== undefined) {
+    assertHeaderObject(value.tools, `${at}.tools`);
+    assertKnownKeys(
+      value.tools,
+      ["relayfile", "mcp"],
+      `${at}.tools`,
+    );
+    assertOptionalStringArray(value.tools, "relayfile", `${at}.tools`);
+    assertOptionalStringArray(value.tools, "mcp", `${at}.tools`);
+  }
+}
+
+function assertHeaderObject(
+  value: unknown,
+  at: string,
+): asserts value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${at}: expected an object`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`${at}: expected a plain object`);
+  }
+}
+
+function assertKnownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  at: string,
+): void {
+  const allowedKeys = new Set<PropertyKey>(allowed);
+  for (const key of Reflect.ownKeys(value)) {
+    if (!allowedKeys.has(key)) {
+      throw new TypeError(`${at}: unknown field ${JSON.stringify(String(key))}`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || !('value' in descriptor)) {
+      throw new TypeError(`${at}.${String(key)}: expected a data property`);
+    }
+  }
+}
+
+function assertOptionalString(
+  value: Record<string, unknown>,
+  key: string,
+  at: string,
+): void {
+  if (value[key] !== undefined && typeof value[key] !== "string") {
+    throw new TypeError(`${at}.${key}: expected a string`);
+  }
+}
+
+function assertOptionalBoolean(
+  value: Record<string, unknown>,
+  key: string,
+  at: string,
+): void {
+  if (value[key] !== undefined && typeof value[key] !== "boolean") {
+    throw new TypeError(`${at}.${key}: expected a boolean`);
+  }
+}
+
+function assertOptionalStringArray(
+  value: Record<string, unknown>,
+  key: string,
+  at: string,
+): void {
+  const candidate = value[key];
+  if (
+    candidate !== undefined
+    && (!Array.isArray(candidate) || candidate.some((item) => typeof item !== "string"))
+  ) {
+    throw new TypeError(`${at}.${key}: expected an array of strings`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  EnrollmentReceipt,
+  Heartbeat,
+  JournalStep,
+  RunJournal,
+  ScheduleState,
+  WorkerSummary,
+  CloudHelper,
+} from "./cloud.js";
+export type { AgentOptions, AgentResult, Ctx } from "./context.js";
+export {
+  COMPLETION_REASONS,
+  RUN_COMPLETION_REASONS,
+  type CompletionReason,
+  type RunCompletionReason,
+} from "./completion.js";
+export type { Step } from "./step.js";
+export {
+  flow,
+  type FlowHandle,
+  type FlowHeader,
+} from "./flow.js";

package/src/runtime.ts

@@ -0,0 +1,7 @@
+export {
+  getFlowDefinition,
+  type AuthoredFlowDefinition,
+  type FlowBody,
+  type FlowHandle,
+  type ReadonlyFlowHeader,
+} from "./flow.js";

package/src/step.ts

@@ -0,0 +1,5 @@
+/** A journal-backed step result with its postfix verification gate. */
+export interface Step<T> extends PromiseLike<T> {
+  /** Fail the step with `verification_failed` when the predicate is false. */
+  gate(predicate: (value: T) => boolean, because?: string): Step<T>;
+}