@sapiom/agent 0.5.0

package/dist/esm/build-manifest.js

@@ -0,0 +1,165 @@
+import { zodToJsonSchema } from "./introspection.js";
+import { MANIFEST_PROTOCOL, } from "./manifest.js";
+export function buildManifest(def, opts) {
+    const steps = {};
+    for (const [stepName, step] of Object.entries(def.steps)) {
+        let inputSchema = null;
+        if (step.inputSchema) {
+            const raw = zodToJsonSchema(step.inputSchema);
+            inputSchema = relaxAdditionalProperties(dropDefaultedFromRequired(raw));
+        }
+        steps[stepName] = {
+            timeoutMs: step.timeoutMs ?? null,
+            inputSchema,
+            transitions: transitionsFor(step),
+        };
+    }
+    return {
+        protocol: MANIFEST_PROTOCOL,
+        name: def.name,
+        entry: def.entry,
+        sdkVersion: opts.sdkVersion,
+        artifact: opts.artifact,
+        steps,
+    };
+}
+function transitionsFor(step) {
+    const transitions = [];
+    for (const target of step.next ?? []) {
+        transitions.push({ kind: "continue", target });
+    }
+    if (step.pause) {
+        transitions.push({
+            kind: "pause",
+            signal: step.pause.signal,
+            resumeStep: step.pause.resumeStep,
+        });
+    }
+    if (step.terminal)
+        transitions.push({ kind: "terminate" });
+    if (step.canFail)
+        transitions.push({ kind: "fail" });
+    return transitions;
+}
+export function validateGraph(manifest) {
+    const errors = [];
+    const names = new Set(Object.keys(manifest.steps));
+    if (!names.has(manifest.entry)) {
+        errors.push(`entry step '${manifest.entry}' is not in the steps map`);
+    }
+    const forward = buildForwardEdges(manifest, names, errors);
+    const warnings = [];
+    if (names.has(manifest.entry)) {
+        const reachable = bfs([manifest.entry], forward);
+        for (const name of names) {
+            if (!reachable.has(name))
+                warnings.push(`step '${name}' is unreachable from entry '${manifest.entry}'`);
+        }
+    }
+    warnings.push(...terminalReachabilityWarnings(manifest, names, forward));
+    return { errors, warnings };
+}
+export function assertValidGraph(manifest) {
+    const { errors, warnings } = validateGraph(manifest);
+    if (errors.length > 0) {
+        throw new Error(`Invalid workflow graph for '${manifest.name}':\n  - ${errors.join("\n  - ")}`);
+    }
+    return warnings;
+}
+function buildForwardEdges(manifest, names, errors) {
+    const forward = new Map();
+    for (const [name, step] of Object.entries(manifest.steps)) {
+        const targets = new Set();
+        for (const t of step.transitions) {
+            if (t.kind === "continue") {
+                if (names.has(t.target))
+                    targets.add(t.target);
+                else
+                    errors.push(`step '${name}' has a continue target '${t.target}' that is not in the steps map`);
+            }
+            else if (t.kind === "pause" && names.has(t.resumeStep)) {
+                targets.add(t.resumeStep);
+            }
+        }
+        if (step.transitions.length === 0) {
+            errors.push(`step '${name}' is a dead-end: it declares no transitions (next/terminal/canFail/pause)`);
+        }
+        forward.set(name, targets);
+    }
+    return forward;
+}
+function terminalReachabilityWarnings(manifest, names, forward) {
+    const sinks = Object.entries(manifest.steps)
+        .filter(([, s]) => s.transitions.some((t) => t.kind === "terminate" || t.kind === "fail"))
+        .map(([name]) => name);
+    if (sinks.length === 0) {
+        return [
+            "no step can terminate or fail — the workflow has no terminal state",
+        ];
+    }
+    const reverse = new Map();
+    for (const name of names)
+        reverse.set(name, new Set());
+    for (const [name, targets] of forward) {
+        for (const t of targets)
+            reverse.get(t)?.add(name);
+    }
+    const canReach = bfs(sinks, reverse);
+    const warnings = [];
+    for (const name of names) {
+        if (!canReach.has(name)) {
+            warnings.push(`step '${name}' cannot reach any terminate/fail (possible unbounded loop or missing terminal)`);
+        }
+    }
+    return warnings;
+}
+function bfs(starts, edges) {
+    const seen = new Set();
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const next of edges.get(cur) ?? [])
+            if (!seen.has(next))
+                queue.push(next);
+    }
+    return seen;
+}
+function relaxAdditionalProperties(value) {
+    if (Array.isArray(value)) {
+        return value.map(relaxAdditionalProperties);
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            if (key === "additionalProperties" && v === false) {
+                continue;
+            }
+            out[key] = relaxAdditionalProperties(v);
+        }
+        return out;
+    }
+    return value;
+}
+function dropDefaultedFromRequired(schema) {
+    const required = schema.required;
+    const properties = schema.properties;
+    if (!Array.isArray(required) ||
+        !properties ||
+        typeof properties !== "object") {
+        return schema;
+    }
+    const props = properties;
+    const filtered = required.filter((key) => {
+        if (typeof key !== "string")
+            return true;
+        const prop = props[key];
+        return !(prop && typeof prop === "object" && "default" in prop);
+    });
+    if (filtered.length === required.length) {
+        return schema;
+    }
+    return { ...schema, required: filtered };
+}

package/dist/esm/context.d.ts

@@ -0,0 +1,47 @@
+import type { Sapiom } from '@sapiom/tools';
+import type { NextStepDirective } from './directives.js';
+export interface StepLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+export type FinishedStepStatus = 'dispatched' | 'succeeded' | 'failed';
+export interface AgentExecutionContext<TShared extends Record<string, unknown> = Record<string, unknown>> {
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly organizationId: string | null;
+    readonly tenantId: string | null;
+    readonly input: unknown;
+    readonly shared: TypedContextStore<TShared>;
+    readonly history: readonly StepExecutionRecord[];
+    readonly attempts: number;
+    readonly logger: StepLogger;
+    readonly sapiom: Sapiom;
+}
+export interface TypedContextStore<TShared extends Record<string, unknown>> {
+    get<K extends keyof TShared>(key: K): TShared[K] | undefined;
+    set<K extends keyof TShared>(key: K, value: TShared[K]): void;
+    has<K extends keyof TShared>(key: K): boolean;
+    snapshot(): Partial<TShared>;
+}
+export interface StepExecutionRecord {
+    readonly stepName: string;
+    readonly attempt: number;
+    readonly status: FinishedStepStatus;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly error: unknown;
+    readonly nextDirective: NextStepDirective | null;
+    readonly sharedStateAfter: Record<string, unknown> | null;
+    readonly startedAt: Date;
+    readonly finishedAt: Date;
+}
+export declare class InMemoryContextStore<TShared extends Record<string, unknown>> implements TypedContextStore<TShared> {
+    private state;
+    constructor(initial?: Partial<TShared>);
+    get<K extends keyof TShared>(key: K): TShared[K] | undefined;
+    set<K extends keyof TShared>(key: K, value: TShared[K]): void;
+    has<K extends keyof TShared>(key: K): boolean;
+    snapshot(): Partial<TShared>;
+}

package/dist/esm/context.js

@@ -0,0 +1,17 @@
+export class InMemoryContextStore {
+    constructor(initial = {}) {
+        this.state = { ...initial };
+    }
+    get(key) {
+        return this.state[key];
+    }
+    set(key, value) {
+        this.state[key] = value;
+    }
+    has(key) {
+        return key in this.state;
+    }
+    snapshot() {
+        return { ...this.state };
+    }
+}

package/dist/esm/directives.d.ts

@@ -0,0 +1,95 @@
+import type { DispatchHandle } from '@sapiom/tools';
+export declare const DIRECTIVE_KIND: {
+    readonly CONTINUE: "continue";
+    readonly RETRY: "retry";
+    readonly PAUSE_UNTIL_SIGNAL: "pause_until_signal";
+    readonly TERMINATE: "terminate";
+    readonly FAIL: "fail";
+};
+export type DirectiveKind = (typeof DIRECTIVE_KIND)[keyof typeof DIRECTIVE_KIND];
+export type NextStepDirective = ContinueDirective | RetryDirective | PauseUntilSignalDirective | TerminateDirective | FailDirective;
+export interface ContinueDirective {
+    readonly kind: typeof DIRECTIVE_KIND.CONTINUE;
+    readonly stepName: string;
+    readonly input?: unknown;
+}
+export interface RetryDirective {
+    readonly kind: typeof DIRECTIVE_KIND.RETRY;
+    readonly delayMs?: number;
+    readonly reason?: string;
+}
+export interface PauseUntilSignalDirective {
+    readonly kind: typeof DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+    readonly signal: {
+        readonly name: string;
+        readonly correlationId?: string;
+    };
+    readonly timeoutMs?: number;
+    readonly resumeStep?: string;
+}
+export interface TerminateDirective {
+    readonly kind: typeof DIRECTIVE_KIND.TERMINATE;
+    readonly reason?: string;
+}
+export interface FailDirective {
+    readonly kind: typeof DIRECTIVE_KIND.FAIL;
+    readonly reason?: string;
+}
+export declare function isContinue(d: NextStepDirective): d is ContinueDirective;
+export declare function isRetry(d: NextStepDirective): d is RetryDirective;
+export declare function isPause(d: NextStepDirective): d is PauseUntilSignalDirective;
+export declare function isTerminate(d: NextStepDirective): d is TerminateDirective;
+export declare function isFail(d: NextStepDirective): d is FailDirective;
+export interface Goto<Target extends string> {
+    readonly kind: typeof DIRECTIVE_KIND.CONTINUE;
+    readonly stepName: Target;
+    readonly input?: unknown;
+}
+export interface Terminate {
+    readonly kind: typeof DIRECTIVE_KIND.TERMINATE;
+    readonly output?: unknown;
+    readonly reason?: string;
+}
+export interface Fail {
+    readonly kind: typeof DIRECTIVE_KIND.FAIL;
+    readonly reason?: string;
+    readonly output?: unknown;
+}
+export interface Pause<Resume extends string> {
+    readonly kind: typeof DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+    readonly signal: {
+        readonly name: string;
+        readonly correlationId?: string;
+    };
+    readonly resumeStep?: Resume;
+    readonly timeoutMs?: number;
+    readonly output?: unknown;
+}
+export interface Retry {
+    readonly kind: typeof DIRECTIVE_KIND.RETRY;
+    readonly delayMs?: number;
+    readonly reason?: string;
+}
+export declare function goto<const Target extends string>(target: Target, output?: unknown): Goto<Target>;
+export declare function terminate(output?: unknown, opts?: {
+    reason?: string;
+}): Terminate;
+export declare function fail(reason?: string, opts?: {
+    output?: unknown;
+}): Fail;
+export declare function pauseUntilSignal<const Resume extends string>(args: {
+    signal: string;
+    resumeStep?: Resume;
+    correlationId?: string;
+    timeoutMs?: number;
+    output?: unknown;
+}): Pause<Resume>;
+export declare function pauseUntilSignal<const Resume extends string>(handle: DispatchHandle | Promise<DispatchHandle>, opts?: {
+    resumeStep?: Resume;
+    timeoutMs?: number;
+    output?: unknown;
+}): Promise<Pause<Resume>>;
+export declare function retry(opts?: {
+    delayMs?: number;
+    reason?: string;
+}): Retry;

package/dist/esm/directives.js

@@ -0,0 +1,61 @@
+export const DIRECTIVE_KIND = {
+    CONTINUE: 'continue',
+    RETRY: 'retry',
+    PAUSE_UNTIL_SIGNAL: 'pause_until_signal',
+    TERMINATE: 'terminate',
+    FAIL: 'fail',
+};
+export function isContinue(d) {
+    return d.kind === DIRECTIVE_KIND.CONTINUE;
+}
+export function isRetry(d) {
+    return d.kind === DIRECTIVE_KIND.RETRY;
+}
+export function isPause(d) {
+    return d.kind === DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+}
+export function isTerminate(d) {
+    return d.kind === DIRECTIVE_KIND.TERMINATE;
+}
+export function isFail(d) {
+    return d.kind === DIRECTIVE_KIND.FAIL;
+}
+export function goto(target, output) {
+    return { kind: DIRECTIVE_KIND.CONTINUE, stepName: target, input: output };
+}
+export function terminate(output, opts) {
+    return { kind: DIRECTIVE_KIND.TERMINATE, output, reason: opts?.reason };
+}
+export function fail(reason, opts) {
+    return { kind: DIRECTIVE_KIND.FAIL, reason, output: opts?.output };
+}
+export function pauseUntilSignal(argOrHandle, opts) {
+    if (isThenable(argOrHandle)) {
+        return Promise.resolve(argOrHandle).then((handle) => pauseFromHandle(handle, opts));
+    }
+    if ('dispatch' in argOrHandle) {
+        return Promise.resolve(pauseFromHandle(argOrHandle, opts));
+    }
+    return {
+        kind: DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL,
+        signal: { name: argOrHandle.signal, correlationId: argOrHandle.correlationId },
+        resumeStep: argOrHandle.resumeStep,
+        timeoutMs: argOrHandle.timeoutMs,
+        output: argOrHandle.output,
+    };
+}
+function isThenable(x) {
+    return x != null && typeof x.then === 'function';
+}
+function pauseFromHandle(handle, opts) {
+    return {
+        kind: DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL,
+        signal: { name: handle.dispatch.resultSignal, correlationId: handle.dispatch.correlationId },
+        resumeStep: opts?.resumeStep,
+        timeoutMs: opts?.timeoutMs,
+        output: opts?.output,
+    };
+}
+export function retry(opts) {
+    return { kind: DIRECTIVE_KIND.RETRY, delayMs: opts?.delayMs, reason: opts?.reason };
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,19 @@
+import type { $ZodIssue } from 'zod/v4/core';
+export declare class AgentError extends Error {
+    constructor(message: string);
+}
+export declare class StepInputValidationError extends AgentError {
+    readonly stepName: string;
+    readonly issues: readonly $ZodIssue[];
+    constructor(stepName: string, issues: readonly $ZodIssue[]);
+}
+export declare class UnknownStepError extends AgentError {
+    readonly stepName: string;
+    constructor(stepName: string);
+}
+export declare class DisallowedTransitionError extends AgentError {
+    readonly stepName: string;
+    readonly directiveKind: string;
+    readonly target?: string;
+    constructor(stepName: string, directiveKind: string, target?: string);
+}

package/dist/esm/errors.js

@@ -0,0 +1,42 @@
+export class AgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentError';
+    }
+}
+export class StepInputValidationError extends AgentError {
+    constructor(stepName, issues) {
+        super(`Input for step '${stepName}' failed validation: ${formatIssues(issues)}`);
+        this.name = 'StepInputValidationError';
+        this.stepName = stepName;
+        this.issues = issues;
+    }
+}
+function formatIssues(issues) {
+    if (issues.length === 0)
+        return 'unknown validation error';
+    return issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `${path}: ${issue.message}`;
+    })
+        .join('; ');
+}
+export class UnknownStepError extends AgentError {
+    constructor(stepName) {
+        super(`Unknown step: ${stepName}`);
+        this.name = 'UnknownStepError';
+        this.stepName = stepName;
+    }
+}
+export class DisallowedTransitionError extends AgentError {
+    constructor(stepName, directiveKind, target) {
+        super(`Step '${stepName}' returned a '${directiveKind}' directive` +
+            (target ? ` to '${target}'` : '') +
+            ` that is not in its declared transitions`);
+        this.name = 'DisallowedTransitionError';
+        this.stepName = stepName;
+        this.directiveKind = directiveKind;
+        this.target = target;
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,17 @@
+export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
+export type { DirectiveKind, NextStepDirective, ContinueDirective, RetryDirective, PauseUntilSignalDirective, TerminateDirective, FailDirective, } from './directives.js';
+export { goto, terminate, fail, pauseUntilSignal, retry } from './directives.js';
+export type { Goto, Terminate, Fail, Pause, Retry } from './directives.js';
+export { defineStep } from './step.js';
+export type { Step, StepResult, StepDefinition, Allowed } from './step.js';
+export type { AgentExecutionContext, TypedContextStore, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
+export { InMemoryContextStore } from './context.js';
+export type { AgentDefinition } from './agent.js';
+export { defineAgent, isAgentDefinition, AGENT_DEFINITION_BRAND } from './agent.js';
+export { AgentError, UnknownStepError, StepInputValidationError, DisallowedTransitionError } from './errors.js';
+export { zodToJsonSchema, exampleFromJsonSchema, stepInputContract, workflowInputContract } from './introspection.js';
+export type { StepInputContract, AgentInputContract } from './introspection.js';
+export { MANIFEST_PROTOCOL, agentManifestSchema } from './manifest.js';
+export type { AgentManifest, AgentStepManifest, ManifestTransition } from './manifest.js';
+export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
+export type { GraphValidation } from './build-manifest.js';

package/dist/esm/index.js

@@ -0,0 +1,9 @@
+export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
+export { goto, terminate, fail, pauseUntilSignal, retry } from './directives.js';
+export { defineStep } from './step.js';
+export { InMemoryContextStore } from './context.js';
+export { defineAgent, isAgentDefinition, AGENT_DEFINITION_BRAND } from './agent.js';
+export { AgentError, UnknownStepError, StepInputValidationError, DisallowedTransitionError } from './errors.js';
+export { zodToJsonSchema, exampleFromJsonSchema, stepInputContract, workflowInputContract } from './introspection.js';
+export { MANIFEST_PROTOCOL, agentManifestSchema } from './manifest.js';
+export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';

package/dist/esm/introspection.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4';
+import type { AgentDefinition } from './agent.js';
+export interface StepInputContract {
+    readonly jsonSchema: Record<string, unknown>;
+    readonly example: unknown;
+}
+export type AgentInputContract = StepInputContract;
+export declare function zodToJsonSchema(schema: z.ZodType): Record<string, unknown>;
+export declare function stepInputContract(def: AgentDefinition<unknown, Record<string, unknown>>, stepName: string): StepInputContract | null;
+export declare function workflowInputContract(def: AgentDefinition<unknown, Record<string, unknown>>): StepInputContract | null;
+export declare function exampleFromJsonSchema(jsonSchema: Record<string, unknown>): unknown;

package/dist/esm/introspection.js

@@ -0,0 +1,56 @@
+import { z } from 'zod/v4';
+export function zodToJsonSchema(schema) {
+    return z.toJSONSchema(schema);
+}
+export function stepInputContract(def, stepName) {
+    const schema = def.steps[stepName]?.inputSchema;
+    if (!schema)
+        return null;
+    const jsonSchema = zodToJsonSchema(schema);
+    return { jsonSchema, example: exampleFromJsonSchema(jsonSchema) };
+}
+export function workflowInputContract(def) {
+    return stepInputContract(def, def.entry);
+}
+export function exampleFromJsonSchema(jsonSchema) {
+    const examples = jsonSchema.examples;
+    if (Array.isArray(examples) && examples.length > 0) {
+        return examples[0];
+    }
+    if ('example' in jsonSchema && jsonSchema.example !== undefined) {
+        return jsonSchema.example;
+    }
+    return skeletonFromJsonSchema(jsonSchema);
+}
+function skeletonFromJsonSchema(schema) {
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    const branches = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(branches) && branches.length > 0) {
+        return skeletonFromJsonSchema(branches[0]);
+    }
+    switch (schema.type) {
+        case 'object': {
+            const props = (schema.properties ?? {});
+            const out = {};
+            for (const [key, value] of Object.entries(props)) {
+                out[key] = skeletonFromJsonSchema(value);
+            }
+            return out;
+        }
+        case 'array':
+            return [];
+        case 'string':
+            return '';
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'null':
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/esm/manifest.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod/v4';
+export declare const MANIFEST_PROTOCOL: 1;
+export type ManifestTransition = {
+    readonly kind: 'continue';
+    readonly target: string;
+} | {
+    readonly kind: 'terminate';
+} | {
+    readonly kind: 'fail';
+} | {
+    readonly kind: 'pause';
+    readonly signal: string;
+    readonly resumeStep: string;
+};
+export interface AgentStepManifest {
+    readonly timeoutMs: number | null;
+    readonly inputSchema: Record<string, unknown> | null;
+    readonly transitions: readonly ManifestTransition[];
+}
+export interface AgentManifest {
+    readonly protocol: typeof MANIFEST_PROTOCOL;
+    readonly name: string;
+    readonly entry: string;
+    readonly sdkVersion: string;
+    readonly artifact: {
+        readonly sha256: string;
+        readonly entryFile: string;
+    };
+    readonly steps: Readonly<Record<string, AgentStepManifest>>;
+}
+export declare const agentManifestSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    name: z.ZodString;
+    entry: z.ZodString;
+    sdkVersion: z.ZodString;
+    artifact: z.ZodObject<{
+        sha256: z.ZodString;
+        entryFile: z.ZodString;
+    }, z.core.$strip>;
+    steps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        timeoutMs: z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>;
+        inputSchema: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>;
+        transitions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"continue">;
+            target: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"terminate">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"fail">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"pause">;
+            signal: z.ZodString;
+            resumeStep: z.ZodString;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/esm/manifest.js

@@ -0,0 +1,24 @@
+import { z } from 'zod/v4';
+export const MANIFEST_PROTOCOL = 1;
+const manifestTransitionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('continue'), target: z.string().min(1) }),
+    z.object({ kind: z.literal('terminate') }),
+    z.object({ kind: z.literal('fail') }),
+    z.object({ kind: z.literal('pause'), signal: z.string().min(1), resumeStep: z.string().min(1) }),
+]);
+const workflowStepManifestSchema = z.object({
+    timeoutMs: z.union([z.number().int().positive(), z.null()]),
+    inputSchema: z.union([z.record(z.string(), z.unknown()), z.null()]),
+    transitions: z.array(manifestTransitionSchema),
+});
+export const agentManifestSchema = z.object({
+    protocol: z.literal(MANIFEST_PROTOCOL),
+    name: z.string().min(1),
+    entry: z.string().min(1),
+    sdkVersion: z.string().min(1),
+    artifact: z.object({
+        sha256: z.string().min(1),
+        entryFile: z.string().min(1),
+    }),
+    steps: z.record(z.string(), workflowStepManifestSchema),
+});

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/esm/step.d.ts

@@ -0,0 +1,42 @@
+import type { ZodType } from 'zod/v4';
+import type { AgentExecutionContext } from './context.js';
+import type { Fail, Goto, NextStepDirective, Pause, Retry, Terminate } from './directives.js';
+export interface Step<TIn = unknown, TOut = unknown, TShared extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    readonly inputSchema?: ZodType<TIn>;
+    readonly timeoutMs?: number;
+    run(input: TIn, ctx: AgentExecutionContext<TShared>): Promise<StepResult<TOut>>;
+}
+export interface StepResult<TOut = unknown> {
+    readonly output: TOut;
+    readonly next: NextStepDirective;
+}
+export type Allowed<Next extends readonly string[], Term extends boolean, CanFail extends boolean, PauseTo extends string> = Goto<Next[number]> | (Term extends true ? Terminate : never) | (CanFail extends true ? Fail : never) | ([PauseTo] extends [never] ? never : Pause<PauseTo>) | Retry;
+export interface StepDefinition<TShared extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    readonly next: readonly string[];
+    readonly terminal: boolean;
+    readonly canFail: boolean;
+    readonly pause?: {
+        readonly signal: string;
+        readonly resumeStep: string;
+    };
+    readonly inputSchema?: ZodType<unknown>;
+    readonly timeoutMs?: number;
+    run(input: unknown, ctx: AgentExecutionContext<TShared>): Promise<NextStepDirective>;
+}
+export declare function defineStep<TIn = unknown, TShared extends Record<string, unknown> = Record<string, unknown>, const Next extends readonly string[] = readonly [], const Term extends boolean = false, const CanFail extends boolean = false, const PauseDecl extends {
+    signal: string;
+    resumeStep: string;
+} | undefined = undefined>(def: {
+    name: string;
+    next?: Next;
+    terminal?: Term;
+    canFail?: CanFail;
+    pause?: PauseDecl;
+    inputSchema?: ZodType<TIn>;
+    timeoutMs?: number;
+    run: (input: TIn, ctx: AgentExecutionContext<TShared>) => Promise<Allowed<Next, Term, CanFail, PauseDecl extends {
+        resumeStep: infer R extends string;
+    } ? R : never>>;
+}): StepDefinition<TShared>;