@sapiom/agent-core 0.6.0

package/dist/cjs/check.js

@@ -0,0 +1,154 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.check = check;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const agent_1 = require("@sapiom/agent");
+const esbuild = __importStar(require("esbuild"));
+const errors_js_1 = require("./errors.js");
+function runTypecheck(sourceDir) {
+    const tscBin = node_path_1.default.join(sourceDir, 'node_modules', '.bin', 'tsc');
+    if (!(0, node_fs_1.existsSync)(tscBin)) {
+        return 'typecheck skipped — TypeScript is not installed (run npm install first)';
+    }
+    try {
+        (0, node_child_process_1.execFileSync)(tscBin, ['--noEmit'], { cwd: sourceDir, stdio: ['ignore', 'pipe', 'pipe'] });
+        return null;
+    }
+    catch (err) {
+        const e = err;
+        const output = (e.stdout?.toString() ?? '').trim() || (e.stderr?.toString() ?? '').trim();
+        throw new errors_js_1.AgentOperationError({
+            code: 'TYPECHECK_FAILED',
+            message: 'The agent has type errors.',
+            hint: output || 'Run `tsc --noEmit` for details.',
+        });
+    }
+}
+const LOCAL_SDK_VERSION = '0.0.0-local';
+async function check(opts) {
+    const { sourceDir } = opts;
+    const entryFile = node_path_1.default.join(sourceDir, 'index.ts');
+    if (!(0, node_fs_1.existsSync)(entryFile)) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an agent project, or pass its directory.',
+        });
+    }
+    const warnings = [];
+    const typecheckSkip = runTypecheck(sourceDir);
+    if (typecheckSkip)
+        warnings.push(typecheckSkip);
+    const tmp = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sapiom-check-'));
+    const bundlePath = node_path_1.default.join(tmp, 'definition.mjs');
+    try {
+        try {
+            await esbuild.build({
+                entryPoints: [entryFile],
+                outfile: bundlePath,
+                bundle: true,
+                platform: 'node',
+                target: 'node20',
+                format: 'esm',
+                logLevel: 'silent',
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the agent.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const mod = await Promise.resolve(`${`file://${bundlePath}?t=${Date.now()}`}`).then(s => __importStar(require(s)));
+        const defs = [];
+        for (const value of Object.values(mod)) {
+            if ((0, agent_1.isAgentDefinition)(value) && !defs.includes(value))
+                defs.push(value);
+        }
+        if (defs.length === 0) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'NO_DEFINITION',
+                message: 'No agent was exported from index.ts.',
+                hint: 'Export the result of defineAgent({ … }).',
+            });
+        }
+        if (defs.length > 1) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'MULTIPLE_DEFINITIONS',
+                message: 'index.ts exports more than one agent.',
+                hint: 'Export exactly one defineAgent({ … }) result.',
+            });
+        }
+        const def = defs[0];
+        const sha256 = (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(bundlePath)).digest('hex');
+        let manifest;
+        try {
+            manifest = agent_1.agentManifestSchema.parse((0, agent_1.buildManifest)(def, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        }
+        catch (err) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'MANIFEST_INVALID',
+                message: 'The agent produced an invalid manifest.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        try {
+            warnings.push(...(0, agent_1.assertValidGraph)(manifest));
+        }
+        catch (err) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'GRAPH_INVALID',
+                message: 'The agent graph is invalid.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const steps = manifest.steps;
+        const stepCount = Array.isArray(steps) ? steps.length : Object.keys(steps ?? {}).length;
+        const name = manifest.name ?? 'agent';
+        return { name, stepCount, warnings, manifest };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(tmp, { recursive: true, force: true });
+    }
+}

package/dist/cjs/client.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_WORKFLOWS_HOST = "https://api.sapiom.ai";
+export interface ClientOptions {
+    host?: string;
+    apiKey: string;
+}
+export interface GatewayErrorBody {
+    message?: string | string[];
+}
+export declare class GatewayClient {
+    private readonly base;
+    private readonly apiKey;
+    constructor(opts: ClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    openStream(path: string, opts?: {
+        signal?: AbortSignal;
+        lastEventId?: string;
+    }): Promise<Response>;
+}
+export declare function createClient(opts: ClientOptions): GatewayClient;

package/dist/cjs/client.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayClient = exports.DEFAULT_WORKFLOWS_HOST = void 0;
+exports.createClient = createClient;
+const errors_js_1 = require("./errors.js");
+exports.DEFAULT_WORKFLOWS_HOST = 'https://api.sapiom.ai';
+class GatewayClient {
+    constructor(opts) {
+        const host = (opts.host ?? exports.DEFAULT_WORKFLOWS_HOST).replace(/\/$/, '');
+        this.base = `${host}/v1/workflows`;
+        this.apiKey = opts.apiKey;
+    }
+    async request(method, path, body) {
+        let res;
+        try {
+            res = await fetch(`${this.base}${path}`, {
+                method,
+                headers: { 'x-api-key': this.apiKey, 'content-type': 'application/json' },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'NETWORK',
+                message: `Could not reach ${this.base}.`,
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const text = await res.text();
+        const data = text ? safeParse(text) : undefined;
+        if (!res.ok) {
+            throw new errors_js_1.AgentOperationError({
+                code: `HTTP_${res.status}`,
+                message: messageFrom(data) ?? `Request failed (${res.status} ${res.statusText}).`,
+                hint: res.status === 401 || res.status === 403
+                    ? 'Check your API key (`sapiom login` or SAPIOM_API_KEY) and that it has access to this agent.'
+                    : undefined,
+            });
+        }
+        return data;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async openStream(path, opts = {}) {
+        const headers = {
+            'x-api-key': this.apiKey,
+            accept: 'text/event-stream',
+        };
+        if (opts.lastEventId) {
+            headers['last-event-id'] = opts.lastEventId;
+        }
+        let res;
+        try {
+            res = await fetch(`${this.base}${path}`, { method: 'GET', headers, signal: opts.signal });
+        }
+        catch (err) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'NETWORK',
+                message: `Could not reach ${this.base}.`,
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            const data = text ? safeParse(text) : undefined;
+            throw new errors_js_1.AgentOperationError({
+                code: `HTTP_${res.status}`,
+                message: messageFrom(data) ?? `Stream request failed (${res.status} ${res.statusText}).`,
+                hint: res.status === 401 || res.status === 403
+                    ? 'Check your API key (`sapiom login` or SAPIOM_API_KEY) and that it has access to this agent.'
+                    : undefined,
+            });
+        }
+        if (!res.body) {
+            throw new errors_js_1.AgentOperationError({
+                code: 'NETWORK',
+                message: `Stream at ${this.base}${path} returned no body.`,
+            });
+        }
+        return res;
+    }
+}
+exports.GatewayClient = GatewayClient;
+function createClient(opts) {
+    return new GatewayClient(opts);
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function messageFrom(data) {
+    if (data && typeof data === 'object' && 'message' in data) {
+        const m = data.message;
+        if (Array.isArray(m))
+            return m.join('; ');
+        if (typeof m === 'string')
+            return m;
+    }
+    return undefined;
+}

package/dist/cjs/clone.d.ts

@@ -0,0 +1,17 @@
+import { GatewayClient } from './client.js';
+import { type CloneRepoOptions } from './git.js';
+export interface CloneOptions {
+    templateId?: string;
+    forkId?: string;
+    targetDir: string;
+    cloneRepo?: (opts: CloneRepoOptions) => void;
+}
+export interface CloneResult {
+    forkId: string;
+    templateId?: string;
+    repoFullName: string;
+    defaultBranch: string;
+    targetDir: string;
+    tokenExpiresAt: string;
+}
+export declare function clone(opts: CloneOptions, client: GatewayClient): Promise<CloneResult>;

package/dist/cjs/clone.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clone = clone;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+const git_js_1 = require("./git.js");
+async function clone(opts, client) {
+    const { templateId, forkId, targetDir } = opts;
+    const runClone = opts.cloneRepo ?? git_js_1.cloneRepo;
+    if (!templateId && !forkId) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BAD_INPUT',
+            message: 'Provide a templateId (to fork then clone) or a forkId (to clone an existing fork).',
+        });
+    }
+    if (templateId && forkId) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BAD_INPUT',
+            message: 'Provide only one of templateId or forkId, not both.',
+            hint: 'Use templateId to start from a gallery template, or forkId to re-clone an existing fork.',
+        });
+    }
+    if ((0, node_fs_1.existsSync)(targetDir) && (0, node_fs_1.readdirSync)(targetDir).length > 0) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'DIR_NOT_EMPTY',
+            message: `Target directory '${targetDir}' already exists and is not empty.`,
+        });
+    }
+    let resolvedForkId = forkId ?? '';
+    let resolvedTemplateId = templateId;
+    if (templateId) {
+        const fork = await client.post(`/templates/${encodeURIComponent(templateId)}/fork`, {});
+        resolvedForkId = fork.id;
+        resolvedTemplateId = fork.templateId;
+    }
+    const token = await client.post(`/forks/${encodeURIComponent(resolvedForkId)}/clone-token`, {});
+    if (!token.cloneUrl.startsWith('https://')) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BAD_CLONE_URL',
+            message: 'The clone token endpoint returned an unexpected clone URL.',
+        });
+    }
+    const parent = node_path_1.default.dirname(node_path_1.default.resolve(targetDir));
+    (0, node_fs_1.mkdirSync)(parent, { recursive: true });
+    runClone({
+        cloneUrl: token.cloneUrl,
+        targetDir,
+        branch: token.defaultBranch,
+        repoFullName: token.repoFullName,
+        cwd: parent,
+    });
+    (0, config_js_1.writeConfig)(targetDir, {
+        repoFullName: token.repoFullName,
+        defaultBranch: token.defaultBranch,
+        forkId: resolvedForkId,
+        ...(resolvedTemplateId ? { templateId: resolvedTemplateId } : {}),
+    });
+    return {
+        forkId: resolvedForkId,
+        ...(resolvedTemplateId ? { templateId: resolvedTemplateId } : {}),
+        repoFullName: token.repoFullName,
+        defaultBranch: token.defaultBranch,
+        targetDir,
+        tokenExpiresAt: token.expiresAt,
+    };
+}

package/dist/cjs/config.d.ts

@@ -0,0 +1,16 @@
+export declare const CONFIG_FILE = "sapiom.json";
+export interface SapiomConfig {
+    definitionId?: string;
+    name?: string;
+    host?: string;
+    templateId?: string;
+    forkId?: string;
+    repoFullName?: string;
+    defaultBranch?: string;
+}
+export declare function readConfig(dir: string): SapiomConfig | null;
+export type LinkedSapiomConfig = SapiomConfig & {
+    definitionId: string;
+};
+export declare function requireConfig(dir: string): LinkedSapiomConfig;
+export declare function writeConfig(dir: string, cfg: SapiomConfig): void;

package/dist/cjs/config.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILE = void 0;
+exports.readConfig = readConfig;
+exports.requireConfig = requireConfig;
+exports.writeConfig = writeConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+exports.CONFIG_FILE = 'sapiom.json';
+function readConfig(dir) {
+    const file = node_path_1.default.join(dir, exports.CONFIG_FILE);
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch {
+        throw new errors_js_1.AgentOperationError({ code: 'BAD_CONFIG', message: `${exports.CONFIG_FILE} is not valid JSON.` });
+    }
+}
+function requireConfig(dir) {
+    const cfg = readConfig(dir);
+    if (!cfg?.definitionId) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'NOT_LINKED',
+            message: 'This project is not linked to a Sapiom agent.',
+            hint: 'Run: sapiom agents link <name>',
+        });
+    }
+    return cfg;
+}
+function writeConfig(dir, cfg) {
+    const existing = readConfig(dir) ?? {};
+    const merged = { ...existing, ...cfg };
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(dir, exports.CONFIG_FILE), JSON.stringify(merged, null, 2) + '\n');
+}

package/dist/cjs/decode.d.ts

@@ -0,0 +1,4 @@
+import type { CostNode, ExecutionProjection, ExecutionRef } from "./types.js";
+export declare function decodeCostNode(raw: unknown): CostNode | null;
+export declare function decodeExecutionRef(raw: unknown): ExecutionRef;
+export declare function decodeExecutionProjection(raw: unknown): ExecutionProjection;

package/dist/cjs/decode.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeCostNode = decodeCostNode;
+exports.decodeExecutionRef = decodeExecutionRef;
+exports.decodeExecutionProjection = decodeExecutionProjection;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function rec(v) {
+    return isRecord(v) ? v : {};
+}
+function str(fallback, ...candidates) {
+    for (const c of candidates)
+        if (typeof c === "string")
+            return c;
+    return fallback;
+}
+function strOrNull(...candidates) {
+    for (const c of candidates)
+        if (typeof c === "string")
+            return c;
+    return null;
+}
+function numOr(fallback, v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function recordOrNull(v) {
+    return isRecord(v) ? v : null;
+}
+const SETTLE_STATES = ["pending", "settling", "final"];
+function settleState(v) {
+    return typeof v === "string" && SETTLE_STATES.includes(v)
+        ? v
+        : "final";
+}
+function decodeCostNode(raw) {
+    if (!isRecord(raw))
+        return null;
+    return {
+        authorizedUsd: str("0", raw.authorizedUsd),
+        capturedUsd: str("0", raw.capturedUsd),
+        settleState: settleState(raw.settleState),
+    };
+}
+function decodeStepErrorFrame(raw) {
+    const r = rec(raw);
+    const frame = {};
+    if (typeof r.function === "string")
+        frame.function = r.function;
+    if (typeof r.file === "string")
+        frame.file = r.file;
+    if (typeof r.line === "number")
+        frame.line = r.line;
+    if (typeof r.column === "number")
+        frame.column = r.column;
+    return frame;
+}
+function decodeStepErrorTrace(raw) {
+    if (typeof raw === "string") {
+        return { frames: [], sourceMapped: false, raw };
+    }
+    if (!isRecord(raw))
+        return null;
+    const trace = {
+        frames: Array.isArray(raw.frames) ? raw.frames.map(decodeStepErrorFrame) : [],
+        sourceMapped: raw.sourceMapped === true,
+    };
+    if (typeof raw.raw === "string")
+        trace.raw = raw.raw;
+    return trace;
+}
+function decodeStepError(raw) {
+    if (!isRecord(raw))
+        return null;
+    const message = strOrNull(raw.message);
+    if (message === null)
+        return null;
+    return {
+        message,
+        trace: decodeStepErrorTrace(raw.trace ?? raw.stack ?? null),
+        traceUnavailableReason: strOrNull(raw.traceUnavailableReason),
+    };
+}
+function decodeStepEvent(raw) {
+    const r = rec(raw);
+    return {
+        sourceId: str("", r.sourceId),
+        sequence: numOr(0, r.sequence),
+        kind: str("", r.kind),
+        payload: recordOrNull(r.payload) ?? {},
+        eventTs: strOrNull(r.eventTs),
+    };
+}
+function decodeDispatchRef(raw) {
+    if (!isRecord(raw))
+        return null;
+    return {
+        childExecutionId: str("", raw.childExecutionId, raw.targetId, raw.executionId),
+        targetType: str("", raw.targetType),
+        correlationId: str("", raw.correlationId),
+        status: str("", raw.status),
+    };
+}
+function decodeExecutionRef(raw) {
+    const r = rec(raw);
+    const executionId = str("", r.executionId, r.id);
+    return {
+        executionId,
+        traceRoot: str(executionId, r.traceRoot, r.rootExecutionId),
+        name: str("", r.name),
+        status: str("", r.status),
+    };
+}
+function decodeStep(raw) {
+    const r = rec(raw);
+    return {
+        stepName: str("", r.stepName),
+        stepOrder: numOr(0, r.stepOrder),
+        attempt: numOr(0, r.attempt),
+        status: str("", r.status),
+        spanId: strOrNull(r.spanId),
+        startedAt: strOrNull(r.startedAt),
+        finishedAt: strOrNull(r.finishedAt),
+        input: r.input ?? null,
+        output: r.output ?? null,
+        sharedStateAfter: recordOrNull(r.sharedStateAfter),
+        nextDirective: r.nextDirective ?? null,
+        cost: decodeCostNode(r.cost),
+        logs: r.logs ?? null,
+        events: Array.isArray(r.events) ? r.events.map(decodeStepEvent) : [],
+        error: decodeStepError(r.error),
+        dispatch: decodeDispatchRef(r.dispatch),
+    };
+}
+function decodeExecutionProjection(raw) {
+    const r = rec(raw);
+    const id = str("", r.id, r.executionId);
+    const traceRoot = str(id, r.traceRoot, r.rootExecutionId);
+    const traceParent = strOrNull(r.traceParent, r.parentExecutionId);
+    return {
+        id,
+        name: str("", r.name),
+        organizationId: strOrNull(r.organizationId),
+        tenantId: strOrNull(r.tenantId),
+        status: str("", r.status),
+        currentStep: strOrNull(r.currentStep),
+        currentStepAttempt: numOr(0, r.currentStepAttempt),
+        version: numOr(0, r.version),
+        definitionId: strOrNull(r.definitionId),
+        buildRunId: strOrNull(r.buildRunId),
+        idempotencyKey: strOrNull(r.idempotencyKey),
+        pausedSignalName: strOrNull(r.pausedSignalName),
+        pausedSignalCorrelationId: strOrNull(r.pausedSignalCorrelationId),
+        pausedUntil: strOrNull(r.pausedUntil),
+        startedAt: str("", r.startedAt),
+        finishedAt: strOrNull(r.finishedAt),
+        input: r.input ?? null,
+        sharedState: recordOrNull(r.sharedState) ?? {},
+        output: r.output ?? null,
+        error: r.error ?? null,
+        pausedStepInputSchema: recordOrNull(r.pausedStepInputSchema),
+        pausedStepInputExample: r.pausedStepInputExample ?? null,
+        traceRoot,
+        rootExecutionId: str(traceRoot, r.rootExecutionId, r.traceRoot),
+        traceParent,
+        parentExecutionId: strOrNull(r.parentExecutionId, r.traceParent),
+        traceId: strOrNull(r.traceId),
+        children: Array.isArray(r.children) ? r.children.map(decodeExecutionRef) : [],
+        cost: decodeCostNode(r.cost),
+        steps: Array.isArray(r.steps) ? r.steps.map(decodeStep) : [],
+    };
+}

package/dist/cjs/deploy.d.ts

@@ -0,0 +1,12 @@
+import { GatewayClient } from './client.js';
+export interface DeployOptions {
+    projectDir: string;
+    definitionId: string;
+    branch?: string;
+}
+export interface DeployResult {
+    definitionId: string;
+    buildRunId: string;
+    status: string;
+}
+export declare function deploy(opts: DeployOptions, client: GatewayClient): Promise<DeployResult>;