@sapiom/agent 0.5.0

package/dist/cjs/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/cjs/directives.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTIVE_KIND = void 0;
+exports.isContinue = isContinue;
+exports.isRetry = isRetry;
+exports.isPause = isPause;
+exports.isTerminate = isTerminate;
+exports.isFail = isFail;
+exports.goto = goto;
+exports.terminate = terminate;
+exports.fail = fail;
+exports.pauseUntilSignal = pauseUntilSignal;
+exports.retry = retry;
+exports.DIRECTIVE_KIND = {
+    CONTINUE: 'continue',
+    RETRY: 'retry',
+    PAUSE_UNTIL_SIGNAL: 'pause_until_signal',
+    TERMINATE: 'terminate',
+    FAIL: 'fail',
+};
+function isContinue(d) {
+    return d.kind === exports.DIRECTIVE_KIND.CONTINUE;
+}
+function isRetry(d) {
+    return d.kind === exports.DIRECTIVE_KIND.RETRY;
+}
+function isPause(d) {
+    return d.kind === exports.DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+}
+function isTerminate(d) {
+    return d.kind === exports.DIRECTIVE_KIND.TERMINATE;
+}
+function isFail(d) {
+    return d.kind === exports.DIRECTIVE_KIND.FAIL;
+}
+function goto(target, output) {
+    return { kind: exports.DIRECTIVE_KIND.CONTINUE, stepName: target, input: output };
+}
+function terminate(output, opts) {
+    return { kind: exports.DIRECTIVE_KIND.TERMINATE, output, reason: opts?.reason };
+}
+function fail(reason, opts) {
+    return { kind: exports.DIRECTIVE_KIND.FAIL, reason, output: opts?.output };
+}
+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: exports.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: exports.DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL,
+        signal: { name: handle.dispatch.resultSignal, correlationId: handle.dispatch.correlationId },
+        resumeStep: opts?.resumeStep,
+        timeoutMs: opts?.timeoutMs,
+        output: opts?.output,
+    };
+}
+function retry(opts) {
+    return { kind: exports.DIRECTIVE_KIND.RETRY, delayMs: opts?.delayMs, reason: opts?.reason };
+}

package/dist/cjs/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/cjs/errors.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisallowedTransitionError = exports.UnknownStepError = exports.StepInputValidationError = exports.AgentError = void 0;
+class AgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentError';
+    }
+}
+exports.AgentError = AgentError;
+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;
+    }
+}
+exports.StepInputValidationError = StepInputValidationError;
+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('; ');
+}
+class UnknownStepError extends AgentError {
+    constructor(stepName) {
+        super(`Unknown step: ${stepName}`);
+        this.name = 'UnknownStepError';
+        this.stepName = stepName;
+    }
+}
+exports.UnknownStepError = UnknownStepError;
+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;
+    }
+}
+exports.DisallowedTransitionError = DisallowedTransitionError;

package/dist/cjs/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/cjs/index.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidGraph = exports.validateGraph = exports.buildManifest = exports.agentManifestSchema = exports.MANIFEST_PROTOCOL = exports.workflowInputContract = exports.stepInputContract = exports.exampleFromJsonSchema = exports.zodToJsonSchema = exports.DisallowedTransitionError = exports.StepInputValidationError = exports.UnknownStepError = exports.AgentError = exports.AGENT_DEFINITION_BRAND = exports.isAgentDefinition = exports.defineAgent = exports.InMemoryContextStore = exports.defineStep = exports.retry = exports.pauseUntilSignal = exports.terminate = exports.goto = exports.isFail = exports.isTerminate = exports.isPause = exports.isRetry = exports.isContinue = exports.DIRECTIVE_KIND = void 0;
+var directives_js_1 = require("./directives.js");
+Object.defineProperty(exports, "DIRECTIVE_KIND", { enumerable: true, get: function () { return directives_js_1.DIRECTIVE_KIND; } });
+Object.defineProperty(exports, "isContinue", { enumerable: true, get: function () { return directives_js_1.isContinue; } });
+Object.defineProperty(exports, "isRetry", { enumerable: true, get: function () { return directives_js_1.isRetry; } });
+Object.defineProperty(exports, "isPause", { enumerable: true, get: function () { return directives_js_1.isPause; } });
+Object.defineProperty(exports, "isTerminate", { enumerable: true, get: function () { return directives_js_1.isTerminate; } });
+Object.defineProperty(exports, "isFail", { enumerable: true, get: function () { return directives_js_1.isFail; } });
+var directives_js_2 = require("./directives.js");
+Object.defineProperty(exports, "goto", { enumerable: true, get: function () { return directives_js_2.goto; } });
+Object.defineProperty(exports, "terminate", { enumerable: true, get: function () { return directives_js_2.terminate; } });
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return directives_js_2.fail; } });
+Object.defineProperty(exports, "pauseUntilSignal", { enumerable: true, get: function () { return directives_js_2.pauseUntilSignal; } });
+Object.defineProperty(exports, "retry", { enumerable: true, get: function () { return directives_js_2.retry; } });
+var step_js_1 = require("./step.js");
+Object.defineProperty(exports, "defineStep", { enumerable: true, get: function () { return step_js_1.defineStep; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "InMemoryContextStore", { enumerable: true, get: function () { return context_js_1.InMemoryContextStore; } });
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "defineAgent", { enumerable: true, get: function () { return agent_js_1.defineAgent; } });
+Object.defineProperty(exports, "isAgentDefinition", { enumerable: true, get: function () { return agent_js_1.isAgentDefinition; } });
+Object.defineProperty(exports, "AGENT_DEFINITION_BRAND", { enumerable: true, get: function () { return agent_js_1.AGENT_DEFINITION_BRAND; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AgentError", { enumerable: true, get: function () { return errors_js_1.AgentError; } });
+Object.defineProperty(exports, "UnknownStepError", { enumerable: true, get: function () { return errors_js_1.UnknownStepError; } });
+Object.defineProperty(exports, "StepInputValidationError", { enumerable: true, get: function () { return errors_js_1.StepInputValidationError; } });
+Object.defineProperty(exports, "DisallowedTransitionError", { enumerable: true, get: function () { return errors_js_1.DisallowedTransitionError; } });
+var introspection_js_1 = require("./introspection.js");
+Object.defineProperty(exports, "zodToJsonSchema", { enumerable: true, get: function () { return introspection_js_1.zodToJsonSchema; } });
+Object.defineProperty(exports, "exampleFromJsonSchema", { enumerable: true, get: function () { return introspection_js_1.exampleFromJsonSchema; } });
+Object.defineProperty(exports, "stepInputContract", { enumerable: true, get: function () { return introspection_js_1.stepInputContract; } });
+Object.defineProperty(exports, "workflowInputContract", { enumerable: true, get: function () { return introspection_js_1.workflowInputContract; } });
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "MANIFEST_PROTOCOL", { enumerable: true, get: function () { return manifest_js_1.MANIFEST_PROTOCOL; } });
+Object.defineProperty(exports, "agentManifestSchema", { enumerable: true, get: function () { return manifest_js_1.agentManifestSchema; } });
+var build_manifest_js_1 = require("./build-manifest.js");
+Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return build_manifest_js_1.buildManifest; } });
+Object.defineProperty(exports, "validateGraph", { enumerable: true, get: function () { return build_manifest_js_1.validateGraph; } });
+Object.defineProperty(exports, "assertValidGraph", { enumerable: true, get: function () { return build_manifest_js_1.assertValidGraph; } });

package/dist/cjs/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/cjs/introspection.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodToJsonSchema = zodToJsonSchema;
+exports.stepInputContract = stepInputContract;
+exports.workflowInputContract = workflowInputContract;
+exports.exampleFromJsonSchema = exampleFromJsonSchema;
+const v4_1 = require("zod/v4");
+function zodToJsonSchema(schema) {
+    return v4_1.z.toJSONSchema(schema);
+}
+function stepInputContract(def, stepName) {
+    const schema = def.steps[stepName]?.inputSchema;
+    if (!schema)
+        return null;
+    const jsonSchema = zodToJsonSchema(schema);
+    return { jsonSchema, example: exampleFromJsonSchema(jsonSchema) };
+}
+function workflowInputContract(def) {
+    return stepInputContract(def, def.entry);
+}
+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/cjs/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/cjs/manifest.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentManifestSchema = exports.MANIFEST_PROTOCOL = void 0;
+const v4_1 = require("zod/v4");
+exports.MANIFEST_PROTOCOL = 1;
+const manifestTransitionSchema = v4_1.z.discriminatedUnion('kind', [
+    v4_1.z.object({ kind: v4_1.z.literal('continue'), target: v4_1.z.string().min(1) }),
+    v4_1.z.object({ kind: v4_1.z.literal('terminate') }),
+    v4_1.z.object({ kind: v4_1.z.literal('fail') }),
+    v4_1.z.object({ kind: v4_1.z.literal('pause'), signal: v4_1.z.string().min(1), resumeStep: v4_1.z.string().min(1) }),
+]);
+const workflowStepManifestSchema = v4_1.z.object({
+    timeoutMs: v4_1.z.union([v4_1.z.number().int().positive(), v4_1.z.null()]),
+    inputSchema: v4_1.z.union([v4_1.z.record(v4_1.z.string(), v4_1.z.unknown()), v4_1.z.null()]),
+    transitions: v4_1.z.array(manifestTransitionSchema),
+});
+exports.agentManifestSchema = v4_1.z.object({
+    protocol: v4_1.z.literal(exports.MANIFEST_PROTOCOL),
+    name: v4_1.z.string().min(1),
+    entry: v4_1.z.string().min(1),
+    sdkVersion: v4_1.z.string().min(1),
+    artifact: v4_1.z.object({
+        sha256: v4_1.z.string().min(1),
+        entryFile: v4_1.z.string().min(1),
+    }),
+    steps: v4_1.z.record(v4_1.z.string(), workflowStepManifestSchema),
+});

package/dist/cjs/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>;

package/dist/cjs/step.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineStep = defineStep;
+function defineStep(def) {
+    return {
+        name: def.name,
+        next: def.next ?? [],
+        terminal: def.terminal ?? false,
+        canFail: def.canFail ?? false,
+        ...(def.pause ? { pause: def.pause } : {}),
+        ...(def.inputSchema ? { inputSchema: def.inputSchema } : {}),
+        ...(def.timeoutMs !== undefined ? { timeoutMs: def.timeoutMs } : {}),
+        run: def.run,
+    };
+}

package/dist/esm/agent.d.ts

@@ -0,0 +1,10 @@
+import type { StepDefinition } from './step.js';
+export declare const AGENT_DEFINITION_BRAND: unique symbol;
+export interface AgentDefinition<TInput = unknown, TShared extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    readonly entry: string;
+    readonly steps: Readonly<Record<string, StepDefinition<TShared>>>;
+    readonly __inputType?: TInput;
+}
+export declare function isAgentDefinition(val: unknown): val is AgentDefinition;
+export declare function defineAgent<TInput = unknown, TShared extends Record<string, unknown> = Record<string, unknown>>(def: AgentDefinition<TInput, TShared>): AgentDefinition<TInput, TShared>;

package/dist/esm/agent.js

@@ -0,0 +1,33 @@
+import { UnknownStepError } from './errors.js';
+export const AGENT_DEFINITION_BRAND = Symbol.for('sapiom.models.definition');
+export function isAgentDefinition(val) {
+    if (val === null || typeof val !== 'object')
+        return false;
+    return val[AGENT_DEFINITION_BRAND] === 1;
+}
+export function defineAgent(def) {
+    if (!def.name) {
+        throw new Error('Agent definition must have a non-empty name');
+    }
+    if (!def.entry) {
+        throw new Error(`Agent '${def.name}' must declare an entry step`);
+    }
+    if (!def.steps[def.entry]) {
+        throw new UnknownStepError(def.entry);
+    }
+    for (const [key, step] of Object.entries(def.steps)) {
+        if (!step) {
+            throw new Error(`Agent '${def.name}' has null/undefined step at key '${key}'`);
+        }
+        if (step.name !== key) {
+            throw new Error(`Agent '${def.name}' step name mismatch at key '${key}': step.name='${step.name}'`);
+        }
+    }
+    Object.defineProperty(def, AGENT_DEFINITION_BRAND, {
+        value: 1,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return def;
+}

package/dist/esm/build-manifest.d.ts

@@ -0,0 +1,15 @@
+import { type AgentManifest } from "./manifest.js";
+import type { AgentDefinition } from "./agent.js";
+export declare function buildManifest(def: AgentDefinition, opts: {
+    sdkVersion: string;
+    artifact: {
+        sha256: string;
+        entryFile: string;
+    };
+}): AgentManifest;
+export interface GraphValidation {
+    readonly errors: string[];
+    readonly warnings: string[];
+}
+export declare function validateGraph(manifest: AgentManifest): GraphValidation;
+export declare function assertValidGraph(manifest: AgentManifest): string[];