@sapiom/agent-core 0.6.0

package/dist/esm/local/stubs.d.ts

@@ -0,0 +1,8 @@
+export declare const STUB_FILE_VERSION = 1;
+export type StubResponse = unknown;
+export type StepStubs = Record<string, StubResponse | StubResponse[]>;
+export interface StubFile {
+    version: number;
+    steps: Record<string, StepStubs>;
+}
+export declare function parseStubFile(raw: unknown): StubFile;

package/dist/esm/local/stubs.js

@@ -0,0 +1,31 @@
+import { AgentOperationError } from '../errors.js';
+export const STUB_FILE_VERSION = 1;
+export function parseStubFile(raw) {
+    if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalid('the stub file must be a JSON object.');
+    }
+    const obj = raw;
+    const version = obj.version ?? STUB_FILE_VERSION;
+    if (typeof version !== 'number') {
+        throw invalid('`version` must be a number.');
+    }
+    const stepsRaw = obj.steps ?? {};
+    if (stepsRaw == null || typeof stepsRaw !== 'object' || Array.isArray(stepsRaw)) {
+        throw invalid('`steps` must be an object keyed by step name.');
+    }
+    const steps = {};
+    for (const [stepName, stepStubs] of Object.entries(stepsRaw)) {
+        if (stepStubs == null || typeof stepStubs !== 'object' || Array.isArray(stepStubs)) {
+            throw invalid(`steps.${stepName} must be an object keyed by capability path.`);
+        }
+        steps[stepName] = stepStubs;
+    }
+    return { version, steps };
+}
+function invalid(detail) {
+    return new AgentOperationError({
+        code: 'STUBS_INVALID',
+        message: `Invalid stub file: ${detail}`,
+        hint: 'Expected { "version": 1, "steps": { "<step>": { "<capability.path>": <response> | [<response>] } } }.',
+    });
+}

package/dist/esm/package.json

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

package/dist/esm/run.d.ts

@@ -0,0 +1,11 @@
+import { GatewayClient } from './client.js';
+export interface RunOptions {
+    definitionId: string;
+    input?: unknown;
+}
+export interface RunResult {
+    executionId: string;
+    raw: Record<string, unknown>;
+}
+export declare function run(opts: RunOptions, client: GatewayClient): Promise<RunResult>;
+export declare function parseJsonInput(raw: string): unknown;

package/dist/esm/run.js

@@ -0,0 +1,25 @@
+import { AgentOperationError } from './errors.js';
+export async function run(opts, client) {
+    const { definitionId, input = {} } = opts;
+    const res = await client.post('/executions', { definitionId, input });
+    const executionId = res.executionId ?? res.id;
+    if (!executionId) {
+        throw new AgentOperationError({
+            code: 'RUN_NO_ID',
+            message: 'The execution was started but no execution id was returned.',
+        });
+    }
+    return { executionId, raw: res };
+}
+export function parseJsonInput(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new AgentOperationError({
+            code: 'BAD_INPUT',
+            message: 'Input is not valid JSON.',
+            hint: 'Pass a valid JSON string, e.g. \'{"key":"value"}\'',
+        });
+    }
+}

package/dist/esm/scaffold.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_TEMPLATE = "default";
+export interface ResolvedVersions {
+    agent: string;
+    tools: string;
+    zod: string;
+}
+export declare function registryFor(pkg: string): string;
+export declare function resolveVersions(): Promise<ResolvedVersions>;
+export declare function listTemplates(templatesDir?: string): string[];
+export declare function resolveTemplate(name: string, templatesDir?: string): string;
+export interface ScaffoldOptions {
+    targetDir: string;
+    template?: string;
+    projectName?: string;
+    templatesDir?: string;
+    versions?: ResolvedVersions;
+}
+export interface ScaffoldResult {
+    targetDir: string;
+    template: string;
+    projectName: string;
+    gitInitialized: boolean;
+}
+export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/esm/scaffold.js

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AgentOperationError } from "./errors.js";
+function resolveModuleDir() {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    try {
+        const metaUrl = eval("import.meta.url");
+        if (typeof metaUrl === "string")
+            return path.dirname(fileURLToPath(metaUrl));
+    }
+    catch {
+    }
+    return "";
+}
+const moduleDir = resolveModuleDir();
+function getTemplatesDir(override) {
+    return (override ??
+        process.env.SAPIOM_TEMPLATES_DIR ??
+        path.resolve(moduleDir, "..", "..", "templates"));
+}
+export const DEFAULT_TEMPLATE = "default";
+const DOTFILE_NAMES = new Set(["_gitignore", "_npmrc"]);
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const VERSION_FALLBACK = {
+    agent: "0.1.1",
+    tools: "0.1.1",
+};
+const ZOD_VERSION = "4.1.12";
+export function registryFor(pkg) {
+    const scope = pkg.startsWith("@") ? pkg.slice(0, pkg.indexOf("/")) : null;
+    const scoped = scope
+        ? process.env[`npm_config_${scope}:registry`]
+        : undefined;
+    const registry = scoped || process.env.npm_config_registry || DEFAULT_REGISTRY;
+    return registry.replace(/\/+$/, "");
+}
+async function latestNpmVersion(pkg) {
+    try {
+        const res = await fetch(`${registryFor(pkg)}/${encodeURIComponent(pkg)}/latest`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        return typeof json.version === "string" ? json.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveVersions() {
+    const [agent, tools] = await Promise.all([
+        latestNpmVersion("@sapiom/agent"),
+        latestNpmVersion("@sapiom/tools"),
+    ]);
+    return {
+        agent: agent ?? VERSION_FALLBACK.agent,
+        tools: tools ?? VERSION_FALLBACK.tools,
+        zod: ZOD_VERSION,
+    };
+}
+export function listTemplates(templatesDir) {
+    const root = getTemplatesDir(templatesDir);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root).filter((name) => statSync(path.join(root, name)).isDirectory());
+}
+export function resolveTemplate(name, templatesDir) {
+    const dir = path.join(getTemplatesDir(templatesDir), name);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        const available = listTemplates(templatesDir);
+        throw new AgentOperationError({
+            code: "UNKNOWN_TEMPLATE",
+            message: `Unknown template '${name}'.` +
+                (available.length
+                    ? ` Available: ${available.join(", ")}.`
+                    : " No templates are bundled."),
+        });
+    }
+    return dir;
+}
+function applyReplacements(file, replacements) {
+    let content;
+    try {
+        content = readFileSync(file, "utf8");
+    }
+    catch {
+        return;
+    }
+    let changed = false;
+    for (const [token, value] of Object.entries(replacements)) {
+        if (content.includes(token)) {
+            content = content.split(token).join(value);
+            changed = true;
+        }
+    }
+    if (changed)
+        writeFileSync(file, content);
+}
+function walk(dir, onFile) {
+    for (const entry of readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, onFile);
+        else
+            onFile(full);
+    }
+}
+function copyTemplate(templateDir, targetDir, replacements) {
+    cpSync(templateDir, targetDir, { recursive: true });
+    walk(targetDir, (file) => {
+        const base = path.basename(file);
+        if (DOTFILE_NAMES.has(base)) {
+            const dotted = path.join(path.dirname(file), "." + base.slice(1));
+            renameSync(file, dotted);
+            applyReplacements(dotted, replacements);
+            return;
+        }
+        applyReplacements(file, replacements);
+    });
+}
+function initGitRepo(dir) {
+    const tryGit = (args) => {
+        try {
+            execFileSync("git", args, { cwd: dir, stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!tryGit(["init"]))
+        return false;
+    tryGit(["add", "-A"]);
+    return (tryGit(["commit", "-m", "Initial commit"]) ||
+        tryGit([
+            "-c",
+            "user.name=Sapiom",
+            "-c",
+            "user.email=noreply@sapiom.ai",
+            "commit",
+            "-m",
+            "Initial commit",
+        ]));
+}
+export async function scaffold(opts) {
+    const { targetDir } = opts;
+    const template = opts.template ?? DEFAULT_TEMPLATE;
+    const projectName = opts.projectName ?? path.basename(targetDir);
+    if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+        throw new AgentOperationError({
+            code: "DIR_NOT_EMPTY",
+            message: `Target directory '${targetDir}' already exists and is not empty.`,
+        });
+    }
+    const templateDir = resolveTemplate(template, opts.templatesDir);
+    const versions = opts.versions ?? (await resolveVersions());
+    mkdirSync(targetDir, { recursive: true });
+    copyTemplate(templateDir, targetDir, {
+        __PROJECT_NAME__: projectName,
+        __AGENT_VERSION__: versions.agent,
+        __TOOLS_VERSION__: versions.tools,
+        __ZOD_VERSION__: versions.zod,
+    });
+    if (!opts.versions) {
+        const sapiomRegistry = registryFor("@sapiom/tools");
+        if (sapiomRegistry !== DEFAULT_REGISTRY) {
+            writeFileSync(path.join(targetDir, ".npmrc"), `@sapiom:registry=${sapiomRegistry}\n`);
+        }
+    }
+    const devDir = path.join(targetDir, ".sapiom-dev");
+    mkdirSync(devDir, { recursive: true });
+    writeFileSync(path.join(devDir, "stubs.json"), JSON.stringify({ version: 1, steps: {} }, null, 2) + "\n");
+    const gitInitialized = initGitRepo(targetDir);
+    return { targetDir, template, projectName, gitInitialized };
+}

package/dist/esm/schedule.d.ts

@@ -0,0 +1,67 @@
+import { GatewayClient } from './client.js';
+export type ScheduleKind = 'schedule_cron' | 'schedule_once';
+export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'disabled';
+export interface SchedulePolicy {
+    catchupPolicy?: 'skip' | 'all';
+    overlapPolicy?: 'allow' | 'skip';
+    jitterMs?: number;
+}
+export interface CreateScheduleOptions {
+    definition: string;
+    kind: ScheduleKind;
+    input?: unknown;
+    cron?: string;
+    timezone?: string;
+    startAt?: string;
+    endAt?: string;
+    policy?: SchedulePolicy;
+    at?: string | Date;
+}
+export interface ScheduleFireRecord {
+    scheduledFor: string;
+    state: string;
+    firedAt: string | null;
+    executionId: string | null;
+    error?: unknown;
+}
+export interface ScheduleSummary {
+    id: string;
+    kind: ScheduleKind;
+    status: ScheduleStatus;
+    definitionSlug: string;
+    cron: string | null;
+    timezone: string | null;
+    nextFireAt: string | null;
+    createdAt: string;
+}
+export interface ScheduleDetail extends ScheduleSummary {
+    input: unknown;
+    startAt: string | null;
+    endAt: string | null;
+    policy: unknown;
+    recentFires: ScheduleFireRecord[];
+}
+export interface ListSchedulesOptions {
+    definition: string;
+    status?: ScheduleStatus;
+    limit?: number;
+    offset?: number;
+}
+export interface CronPreviewOptions {
+    cron: string;
+    timezone?: string;
+    count?: number;
+}
+export interface CronPreview {
+    cron: string;
+    timezone: string;
+    occurrences: string[];
+}
+export declare function createSchedule(opts: CreateScheduleOptions, client: GatewayClient): Promise<ScheduleDetail>;
+export declare function listSchedules(opts: ListSchedulesOptions, client: GatewayClient): Promise<ScheduleSummary[]>;
+export declare function getSchedule(id: string, client: GatewayClient): Promise<ScheduleDetail>;
+export declare function cancelSchedule(id: string, client: GatewayClient): Promise<{
+    id: string;
+    status: ScheduleStatus;
+}>;
+export declare function previewCron(opts: CronPreviewOptions, client: GatewayClient): Promise<CronPreview>;

package/dist/esm/schedule.js

@@ -0,0 +1,26 @@
+export async function createSchedule(opts, client) {
+    const { definition, ...body } = opts;
+    return client.post(`/${encodeURIComponent(definition)}/triggers`, body);
+}
+export async function listSchedules(opts, client) {
+    const { definition, ...filters } = opts;
+    return client.get(`/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
+}
+export async function getSchedule(id, client) {
+    return client.get(`/triggers/${encodeURIComponent(id)}`);
+}
+export async function cancelSchedule(id, client) {
+    return client.request('DELETE', `/triggers/${encodeURIComponent(id)}`);
+}
+export async function previewCron(opts, client) {
+    return client.post('/triggers/preview-cron', opts);
+}
+function toQuery(filters) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) {
+        if (value !== undefined && value !== null)
+            params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}

package/dist/esm/signal.d.ts

@@ -0,0 +1,12 @@
+import { GatewayClient } from './client.js';
+export interface SignalOptions {
+    executionId: string;
+    name: string;
+    correlationId: string;
+    payload?: unknown;
+}
+export interface SignalResult {
+    matched: number;
+}
+export declare function signal(opts: SignalOptions, client: GatewayClient): Promise<SignalResult>;
+export declare function parseSignalPayload(raw: string): unknown;

package/dist/esm/signal.js

@@ -0,0 +1,20 @@
+import { AgentOperationError } from './errors.js';
+export async function signal(opts, client) {
+    const res = await client.post(`/executions/${opts.executionId}/signals`, {
+        name: opts.name,
+        correlationId: opts.correlationId,
+        payload: opts.payload,
+    });
+    return { matched: res.matched ?? 0 };
+}
+export function parseSignalPayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new AgentOperationError({
+            code: 'BAD_PAYLOAD',
+            message: 'Signal payload is not valid JSON.',
+        });
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,99 @@
+export type SettleState = "pending" | "settling" | "final";
+export interface CostNode {
+    authorizedUsd: string;
+    capturedUsd: string;
+    settleState: SettleState;
+}
+export interface StepEvent {
+    sourceId: string;
+    sequence: number;
+    kind: string;
+    payload: Record<string, unknown>;
+    eventTs: string | null;
+}
+export interface StepErrorFrame {
+    function?: string;
+    file?: string;
+    line?: number;
+    column?: number;
+}
+export interface StepErrorTrace {
+    frames: StepErrorFrame[];
+    sourceMapped: boolean;
+    raw?: string;
+}
+export interface StepError {
+    message: string;
+    trace: StepErrorTrace | null;
+    traceUnavailableReason: string | null;
+}
+export declare const SSE_EVENT_TYPES: readonly ["step.started", "step.captured", "cost.updated", "run.paused", "run.resumed", "run.terminal"];
+export type SseEventType = (typeof SSE_EVENT_TYPES)[number];
+export interface SseEvent {
+    type: SseEventType;
+    executionId: string;
+    traceRoot: string | null;
+    nodeId: string | null;
+}
+export interface ExecutionRef {
+    executionId: string;
+    traceRoot: string;
+    name: string;
+    status: string;
+}
+export interface DispatchRef {
+    childExecutionId: string;
+    targetType: string;
+    correlationId: string;
+    status: string;
+}
+export interface StepProjection {
+    stepName: string;
+    stepOrder: number;
+    attempt: number;
+    status: string;
+    spanId: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    input: unknown;
+    output: unknown;
+    sharedStateAfter: Record<string, unknown> | null;
+    nextDirective: unknown;
+    cost: CostNode | null;
+    logs: unknown;
+    events: StepEvent[];
+    error: StepError | null;
+    dispatch: DispatchRef | null;
+}
+export interface ExecutionProjection {
+    id: string;
+    name: string;
+    organizationId: string | null;
+    tenantId: string | null;
+    status: string;
+    currentStep: string | null;
+    currentStepAttempt: number;
+    version: number;
+    definitionId: string | null;
+    buildRunId: string | null;
+    idempotencyKey: string | null;
+    pausedSignalName: string | null;
+    pausedSignalCorrelationId: string | null;
+    pausedUntil: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    input: unknown;
+    sharedState: Record<string, unknown>;
+    output: unknown;
+    error: unknown;
+    pausedStepInputSchema: Record<string, unknown> | null;
+    pausedStepInputExample: unknown;
+    traceRoot: string;
+    rootExecutionId: string;
+    traceParent: string | null;
+    parentExecutionId: string | null;
+    traceId: string | null;
+    children: ExecutionRef[];
+    cost: CostNode | null;
+    steps: StepProjection[];
+}

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+export const SSE_EVENT_TYPES = [
+    "step.started",
+    "step.captured",
+    "cost.updated",
+    "run.paused",
+    "run.resumed",
+    "run.terminal",
+];

package/dist/esm/watch.d.ts

@@ -0,0 +1,10 @@
+import type { GatewayClient } from "./client.js";
+import { type SseEvent } from "./types.js";
+export interface WatchExecutionOptions {
+    executionId: string;
+    lastEventId?: string;
+    signal?: AbortSignal;
+}
+export declare function watchExecution(opts: WatchExecutionOptions, client: GatewayClient): AsyncGenerator<SseEvent>;
+export declare function parseSseFrame(raw: string): SseEvent | null;
+export declare function parseSseEvent(raw: string): SseEvent | null;

package/dist/esm/watch.js

@@ -0,0 +1,96 @@
+import { SSE_EVENT_TYPES } from "./types.js";
+export async function* watchExecution(opts, client) {
+    const controller = new AbortController();
+    const onExternalAbort = () => controller.abort();
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            controller.abort();
+        else
+            opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+    const path = `/executions/${encodeURIComponent(opts.executionId)}/stream`;
+    try {
+        const res = await client.openStream(path, {
+            signal: controller.signal,
+            lastEventId: opts.lastEventId,
+        });
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                for (;;) {
+                    const boundary = indexOfFrameBoundary(buffer);
+                    if (boundary === -1)
+                        break;
+                    const raw = buffer.slice(0, boundary.at);
+                    buffer = buffer.slice(boundary.after);
+                    const event = parseSseFrame(raw);
+                    if (event)
+                        yield event;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    finally {
+        controller.abort();
+        if (opts.signal)
+            opts.signal.removeEventListener("abort", onExternalAbort);
+    }
+}
+function indexOfFrameBoundary(buffer) {
+    const lf = buffer.indexOf("\n\n");
+    const crlf = buffer.indexOf("\r\n\r\n");
+    if (lf === -1 && crlf === -1)
+        return -1;
+    if (crlf !== -1 && (lf === -1 || crlf < lf))
+        return { at: crlf, after: crlf + 4 };
+    return { at: lf, after: lf + 2 };
+}
+export function parseSseFrame(raw) {
+    const dataLines = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data")
+            dataLines.push(value);
+    }
+    if (dataLines.length === 0)
+        return null;
+    return parseSseEvent(dataLines.join("\n"));
+}
+export function parseSseEvent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const m = parsed;
+    if (typeof m.type !== "string" || !SSE_EVENT_TYPES.includes(m.type)) {
+        return null;
+    }
+    if (typeof m.executionId !== "string" || m.executionId.length === 0)
+        return null;
+    return {
+        type: m.type,
+        executionId: m.executionId,
+        traceRoot: typeof m.traceRoot === "string" ? m.traceRoot : null,
+        nodeId: typeof m.nodeId === "string" ? m.nodeId : null,
+    };
+}