@sapiom/agent-core 0.6.0

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchedule = createSchedule;
+exports.listSchedules = listSchedules;
+exports.getSchedule = getSchedule;
+exports.cancelSchedule = cancelSchedule;
+exports.previewCron = previewCron;
+async function createSchedule(opts, client) {
+    const { definition, ...body } = opts;
+    return client.post(`/${encodeURIComponent(definition)}/triggers`, body);
+}
+async function listSchedules(opts, client) {
+    const { definition, ...filters } = opts;
+    return client.get(`/${encodeURIComponent(definition)}/triggers${toQuery(filters)}`);
+}
+async function getSchedule(id, client) {
+    return client.get(`/triggers/${encodeURIComponent(id)}`);
+}
+async function cancelSchedule(id, client) {
+    return client.request('DELETE', `/triggers/${encodeURIComponent(id)}`);
+}
+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/cjs/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/cjs/signal.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signal = signal;
+exports.parseSignalPayload = parseSignalPayload;
+const errors_js_1 = require("./errors.js");
+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 };
+}
+function parseSignalPayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BAD_PAYLOAD',
+            message: 'Signal payload is not valid JSON.',
+        });
+    }
+}

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSE_EVENT_TYPES = void 0;
+exports.SSE_EVENT_TYPES = [
+    "step.started",
+    "step.captured",
+    "cost.updated",
+    "run.paused",
+    "run.resumed",
+    "run.terminal",
+];

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

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchExecution = watchExecution;
+exports.parseSseFrame = parseSseFrame;
+exports.parseSseEvent = parseSseEvent;
+const types_js_1 = require("./types.js");
+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 };
+}
+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"));
+}
+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" || !types_js_1.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,
+    };
+}

package/dist/esm/__tests__/execution-detail.wire.fixture.json

@@ -0,0 +1,101 @@
+{
+    "id": "exec_0001",
+    "name": "daily-digest",
+    "organizationId": "org_0001",
+    "tenantId": "tenant_0001",
+    "status": "failed",
+    "currentStep": "render",
+    "currentStepAttempt": 2,
+    "version": 3,
+    "definitionId": "def_0001",
+    "buildRunId": "build_0001",
+    "idempotencyKey": null,
+    "pausedSignalName": null,
+    "pausedSignalCorrelationId": null,
+    "pausedUntil": null,
+    "startedAt": "2026-01-01T00:00:00.000Z",
+    "finishedAt": "2026-01-01T00:02:30.000Z",
+    "input": { "topic": "weekly-summary" },
+    "sharedState": { "count": 2 },
+    "output": null,
+    "error": null,
+    "pausedStepInputSchema": null,
+    "pausedStepInputExample": null,
+    "repoFullName": "example-org/example-workflows",
+    "pinnedCommitSha": "0000000000000000000000000000000000000000",
+    "traceId": "trace_0001",
+    "traceRoot": "exec_0001",
+    "rootExecutionId": "exec_0001",
+    "traceParent": null,
+    "parentExecutionId": null,
+    "children": [
+        {
+            "executionId": "exec_0002",
+            "targetType": "agent",
+            "correlationId": "exec_0002",
+            "status": "resolved"
+        }
+    ],
+    "steps": [
+        {
+            "id": "step_0001",
+            "stepName": "gather",
+            "stepOrder": 0,
+            "attempt": 1,
+            "status": "completed",
+            "input": { "topic": "weekly-summary" },
+            "output": { "items": 12 },
+            "error": null,
+            "nextDirective": { "kind": "continue" },
+            "sharedStateAfter": { "count": 1 },
+            "logs": [{ "ts": "2026-01-01T00:00:05.000Z", "level": "info", "msg": "fetched 12 items" }],
+            "events": [
+                {
+                    "sourceId": "run_0001",
+                    "sequence": 1,
+                    "kind": "tool_use",
+                    "payload": { "tool": "web.search" },
+                    "eventTs": "2026-01-01T00:00:10.000Z"
+                }
+            ],
+            "spanId": "span_0001",
+            "dispatch": null,
+            "startedAt": "2026-01-01T00:00:00.000Z",
+            "finishedAt": "2026-01-01T00:00:45.000Z"
+        },
+        {
+            "id": "step_0002",
+            "stepName": "render",
+            "stepOrder": 1,
+            "attempt": 2,
+            "status": "failed",
+            "input": { "items": 12 },
+            "output": null,
+            "error": {
+                "message": "template not found",
+                "trace": {
+                    "frames": [
+                        { "function": "render", "file": "src/steps/render.ts", "line": 12, "column": 11 },
+                        { "function": "run", "file": "src/engine/runner.ts", "line": 88, "column": 5 }
+                    ],
+                    "sourceMapped": true,
+                    "raw": "Error: template not found\n    at render (dist/steps/render.mjs:8:9)"
+                },
+                "traceUnavailableReason": null
+            },
+            "nextDirective": null,
+            "sharedStateAfter": { "count": 2 },
+            "logs": null,
+            "events": [],
+            "spanId": "span_0002",
+            "dispatch": {
+                "targetId": "exec_0002",
+                "targetType": "agent",
+                "correlationId": "exec_0002",
+                "status": "resolved"
+            },
+            "startedAt": "2026-01-01T00:00:45.000Z",
+            "finishedAt": "2026-01-01T00:02:30.000Z"
+        }
+    ]
+}

package/dist/esm/__tests__/execution-projection.preseam.fixture.json

@@ -0,0 +1,37 @@
+{
+    "id": "exec_legacy_0001",
+    "name": "old-run",
+    "organizationId": "org_0001",
+    "tenantId": "tenant_0001",
+    "status": "completed",
+    "currentStep": null,
+    "currentStepAttempt": 1,
+    "version": 1,
+    "definitionId": null,
+    "buildRunId": null,
+    "idempotencyKey": null,
+    "pausedSignalName": null,
+    "pausedSignalCorrelationId": null,
+    "pausedUntil": null,
+    "startedAt": "2025-06-01T00:00:00.000Z",
+    "finishedAt": "2025-06-01T00:00:20.000Z",
+    "input": {},
+    "sharedState": {},
+    "output": { "ok": true },
+    "error": null,
+    "steps": [
+        {
+            "stepName": "run",
+            "stepOrder": 0,
+            "attempt": 1,
+            "status": "completed",
+            "input": {},
+            "output": { "ok": true },
+            "error": null,
+            "nextDirective": { "kind": "complete" },
+            "sharedStateAfter": {},
+            "startedAt": "2025-06-01T00:00:00.000Z",
+            "finishedAt": "2025-06-01T00:00:20.000Z"
+        }
+    ]
+}

package/dist/esm/__tests__/execution-projection.with-cost.fixture.json

@@ -0,0 +1,60 @@
+{
+    "id": "exec_0001",
+    "name": "daily-digest",
+    "organizationId": "org_0001",
+    "tenantId": "tenant_0001",
+    "status": "completed",
+    "currentStep": null,
+    "currentStepAttempt": 1,
+    "version": 3,
+    "definitionId": "def_0001",
+    "buildRunId": "build_0001",
+    "idempotencyKey": null,
+    "pausedSignalName": null,
+    "pausedSignalCorrelationId": null,
+    "pausedUntil": null,
+    "startedAt": "2026-01-01T00:00:00.000Z",
+    "finishedAt": "2026-01-01T00:02:30.000Z",
+    "input": { "topic": "weekly-summary" },
+    "sharedState": { "count": 2 },
+    "output": { "url": "https://example.com/report/exec_0001" },
+    "error": null,
+    "pausedStepInputSchema": null,
+    "pausedStepInputExample": null,
+    "traceId": "trace_0001",
+    "traceRoot": "exec_0001",
+    "rootExecutionId": "exec_0001",
+    "traceParent": null,
+    "parentExecutionId": null,
+    "children": [],
+    "cost": {
+        "authorizedUsd": "1.50",
+        "capturedUsd": "1.20",
+        "settleState": "settling"
+    },
+    "steps": [
+        {
+            "id": "step_0001",
+            "stepName": "gather",
+            "stepOrder": 0,
+            "attempt": 1,
+            "status": "completed",
+            "input": { "topic": "weekly-summary" },
+            "output": { "items": 12 },
+            "error": null,
+            "nextDirective": { "kind": "continue" },
+            "sharedStateAfter": { "count": 1 },
+            "logs": null,
+            "events": [],
+            "spanId": "span_0001",
+            "dispatch": null,
+            "cost": {
+                "authorizedUsd": "0.50",
+                "capturedUsd": "0.50",
+                "settleState": "final"
+            },
+            "startedAt": "2026-01-01T00:00:00.000Z",
+            "finishedAt": "2026-01-01T00:00:45.000Z"
+        }
+    ]
+}

package/dist/esm/bundle.d.ts

@@ -0,0 +1,5 @@
+export interface DeployBundle {
+    code: string;
+    dependencies: Record<string, string>;
+}
+export declare function bundleForDeploy(sourceDir: string): Promise<DeployBundle>;

package/dist/esm/bundle.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+import { AgentOperationError } from './errors.js';
+export async function bundleForDeploy(sourceDir) {
+    const entryFile = path.join(sourceDir, 'index.ts');
+    if (!existsSync(entryFile)) {
+        throw new AgentOperationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an agent project, or pass its directory.',
+        });
+    }
+    const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-deploy-bundle-'));
+    const outfile = path.join(tmp, 'index.js');
+    try {
+        let result;
+        try {
+            result = await esbuild.build({
+                entryPoints: [entryFile],
+                outfile,
+                bundle: true,
+                platform: 'node',
+                target: 'node20',
+                format: 'esm',
+                packages: 'external',
+                metafile: true,
+                logLevel: 'silent',
+            });
+        }
+        catch (err) {
+            throw new AgentOperationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the agent for deploy.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const code = readFileSync(outfile, 'utf8');
+        const externals = collectExternalPackages(result.metafile, outfile);
+        const dependencies = resolveInstalledVersions(sourceDir, externals);
+        return { code, dependencies };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+function collectExternalPackages(metafile, outfile) {
+    const key = Object.keys(metafile.outputs).find((k) => path.resolve(k) === path.resolve(outfile));
+    const imports = key ? metafile.outputs[key].imports : [];
+    const names = new Set();
+    for (const imp of imports) {
+        if (!imp.external)
+            continue;
+        const name = packageNameOf(imp.path);
+        if (name && !isBuiltin(name))
+            names.add(name);
+    }
+    return [...names].sort();
+}
+function packageNameOf(importPath) {
+    if (importPath.startsWith('node:'))
+        return null;
+    const parts = importPath.split('/');
+    if (importPath.startsWith('@'))
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+    return parts[0] || null;
+}
+function resolveInstalledVersions(sourceDir, packages) {
+    const deps = {};
+    for (const pkg of packages) {
+        deps[pkg] = readInstalledVersion(sourceDir, pkg) ?? 'latest';
+    }
+    return deps;
+}
+function readInstalledVersion(fromDir, pkg) {
+    let dir = path.resolve(fromDir);
+    while (true) {
+        const pkgJson = path.join(dir, 'node_modules', ...pkg.split('/'), 'package.json');
+        if (existsSync(pkgJson)) {
+            try {
+                const version = JSON.parse(readFileSync(pkgJson, 'utf8')).version;
+                if (version)
+                    return version;
+            }
+            catch {
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/esm/check.d.ts

@@ -0,0 +1,10 @@
+export interface CheckOptions {
+    sourceDir: string;
+}
+export interface CheckResult {
+    name: string;
+    stepCount: number;
+    warnings: string[];
+    manifest: unknown;
+}
+export declare function check(opts: CheckOptions): Promise<CheckResult>;