@predicatelabs/sdk 0.99.9

package/dist/tools/registry.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+exports.defineTool = defineTool;
+const zod_1 = require("../utils/zod");
+function defineTool(spec) {
+    return spec;
+}
+class ToolRegistry {
+    constructor() {
+        this.tools = new Map();
+    }
+    register(spec) {
+        if (this.tools.has(spec.name)) {
+            throw new Error(`tool already registered: ${spec.name}`);
+        }
+        this.tools.set(spec.name, spec);
+        return this;
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return Array.from(this.tools.values());
+    }
+    llmTools() {
+        return this.list().map(spec => ({
+            name: spec.name,
+            description: spec.description ?? '',
+            parameters: spec.parameters ?? (0, zod_1.zodToJsonSchema)(spec.input),
+        }));
+    }
+    validateInput(name, payload) {
+        const spec = this.tools.get(name);
+        if (!spec) {
+            throw new Error(`tool not found: ${name}`);
+        }
+        const parsed = spec.input.safeParse(payload);
+        if (!parsed.success) {
+            throw new Error(parsed.error.message);
+        }
+        return parsed.data;
+    }
+    validateOutput(name, payload) {
+        const spec = this.tools.get(name);
+        if (!spec) {
+            throw new Error(`tool not found: ${name}`);
+        }
+        const parsed = spec.output.safeParse(payload);
+        if (!parsed.success) {
+            throw new Error(parsed.error.message);
+        }
+        return parsed.data;
+    }
+    validateCall(name, payload) {
+        const spec = this.tools.get(name);
+        if (!spec) {
+            throw new Error(`tool not found: ${name}`);
+        }
+        return { input: this.validateInput(name, payload), spec };
+    }
+    async execute(name, payload, ctx = null) {
+        const start = Date.now();
+        const { input, spec } = this.validateCall(name, payload);
+        if (!spec.handler) {
+            throw new Error(`tool has no handler: ${name}`);
+        }
+        const runtime = ctx?.runtime;
+        const tracer = runtime?.tracer;
+        const stepId = runtime?.stepId ?? runtime?.step_id ?? null;
+        try {
+            const result = await Promise.resolve(spec.handler(ctx, input));
+            const validated = this.validateOutput(name, result);
+            if (tracer) {
+                tracer.emit('tool_call', {
+                    tool_name: name,
+                    inputs: input,
+                    outputs: validated,
+                    success: true,
+                    duration_ms: Date.now() - start,
+                }, stepId || undefined);
+            }
+            return validated;
+        }
+        catch (err) {
+            if (tracer) {
+                tracer.emit('tool_call', {
+                    tool_name: name,
+                    inputs: input,
+                    success: false,
+                    error: String(err?.message ?? err),
+                    duration_ms: Date.now() - start,
+                }, stepId || undefined);
+            }
+            throw err;
+        }
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/tracing/cloud-sink.d.ts

@@ -0,0 +1,189 @@
+/**
+ * CloudTraceSink - Enterprise Cloud Upload
+ *
+ * Implements "Local Write, Batch Upload" pattern for cloud tracing
+ *
+ * PRODUCTION HARDENING:
+ * - Uses persistent cache directory (~/.sentience/traces/pending/) to survive crashes
+ * - Supports non-blocking close() to avoid hanging user scripts
+ * - Preserves traces locally on upload failure
+ */
+import { TraceSink } from './sink';
+import { TraceEvent } from './types';
+/**
+ * Optional logger interface for SDK users
+ */
+export interface SentienceLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/**
+ * CloudTraceSink writes trace events to a local temp file,
+ * then uploads the complete trace to cloud storage on close()
+ *
+ * Architecture:
+ * 1. **Local Buffer**: Writes to temp file (zero latency, non-blocking)
+ * 2. **Pre-signed URL**: Uses secure pre-signed PUT URL from backend API
+ * 3. **Batch Upload**: Uploads complete file on close() or at intervals
+ * 4. **Zero Credential Exposure**: Never embeds cloud credentials in SDK
+ *
+ * This design ensures:
+ * - Fast agent performance (microseconds per emit, not milliseconds)
+ * - Security (credentials stay on backend)
+ * - Reliability (network issues don't crash the agent)
+ *
+ * Example:
+ *   const sink = new CloudTraceSink(uploadUrl);
+ *   const tracer = new Tracer(runId, sink);
+ *   tracer.emitRunStart('SentienceAgent');
+ *   await tracer.close(); // Uploads to cloud
+ */
+export declare class CloudTraceSink extends TraceSink {
+    private uploadUrl;
+    private tempFilePath;
+    private runId;
+    private writeStream;
+    private closed;
+    private apiKey?;
+    private apiUrl;
+    private logger?;
+    private traceFileSizeBytes;
+    private screenshotTotalSizeBytes;
+    private screenshotCount;
+    private indexFileSizeBytes;
+    private uploadSuccessful;
+    /**
+     * Create a new CloudTraceSink
+     *
+     * @param uploadUrl - Pre-signed PUT URL from Sentience API
+     * @param runId - Run ID for persistent cache naming
+     * @param apiKey - Sentience API key for calling /v1/traces/complete
+     * @param apiUrl - Sentience API base URL (default: https://api.sentienceapi.com)
+     * @param logger - Optional logger instance for logging file sizes and errors
+     */
+    constructor(uploadUrl: string, runId?: string, apiKey?: string, apiUrl?: string, logger?: SentienceLogger);
+    /**
+     * Emit a trace event to local temp file (fast, non-blocking)
+     *
+     * @param event - Trace event to emit
+     */
+    emit(event: TraceEvent): void;
+    /**
+     * Upload data to cloud using Node's built-in https module
+     */
+    private _uploadToCloud;
+    /**
+     * Upload buffered trace to cloud via pre-signed URL
+     *
+     * @param blocking - If false, upload happens in background (default: true)
+     *
+     * PRODUCTION FIX: Non-blocking mode prevents hanging user scripts
+     * on slow uploads (Risk #2 from production hardening plan)
+     */
+    close(blocking?: boolean): Promise<void>;
+    /**
+     * Internal upload logic (called by both blocking and non-blocking close)
+     */
+    private _doUpload;
+    /**
+     * Infer final status from trace events by reading the trace file.
+     * @returns Final status: "success", "failure", "partial", or "unknown"
+     */
+    private _inferFinalStatusFromTrace;
+    /**
+     * Extract execution statistics from trace file.
+     * @returns Trace statistics for /v1/traces/complete
+     */
+    private _extractStatsFromTrace;
+    /**
+     * Call /v1/traces/complete to report file sizes and stats to gateway.
+     *
+     * This is a best-effort call - failures are logged but don't affect upload success.
+     */
+    private _completeTrace;
+    /**
+     * Generate trace index file (automatic on close)
+     */
+    private generateIndex;
+    /**
+     * Upload trace index file to cloud storage.
+     *
+     * Called after successful trace upload to provide fast timeline rendering.
+     * The index file enables O(1) step lookups without parsing the entire trace.
+     */
+    private _uploadIndex;
+    /**
+     * Request index upload URL from Sentience API
+     */
+    private _requestIndexUploadUrl;
+    /**
+     * Upload index data to cloud using pre-signed URL
+     */
+    private _uploadIndexToCloud;
+    /**
+     * Normalize screenshot data by extracting base64 from data URL if needed.
+     *
+     * Handles both formats:
+     * - Data URL: "data:image/jpeg;base64,/9j/4AAQ..."
+     * - Pure base64: "/9j/4AAQ..."
+     *
+     * @param screenshotRaw - Raw screenshot data (data URL or base64)
+     * @param defaultFormat - Default format if not detected from data URL
+     * @returns Tuple of [base64String, formatString]
+     */
+    private _normalizeScreenshotData;
+    /**
+     * Extract screenshots from trace events.
+     *
+     * @returns Map of sequence number to screenshot data
+     */
+    private _extractScreenshotsFromTrace;
+    /**
+     * Create trace file without screenshot_base64 fields.
+     *
+     * @param outputPath - Path to write cleaned trace file
+     */
+    private _createCleanedTrace;
+    /**
+     * Request pre-signed upload URLs for screenshots from gateway.
+     *
+     * @param sequences - List of screenshot sequence numbers
+     * @returns Map of sequence number to upload URL
+     */
+    private _requestScreenshotUrls;
+    /**
+     * Upload screenshots extracted from trace events.
+     *
+     * Steps:
+     * 1. Request pre-signed URLs from gateway (/v1/screenshots/init)
+     * 2. Decode base64 to image bytes
+     * 3. Upload screenshots in parallel (10 concurrent workers)
+     * 4. Track upload progress
+     *
+     * @param screenshots - Map of sequence to screenshot data
+     */
+    private _uploadScreenshots;
+    /**
+     * Upload a single screenshot to pre-signed URL.
+     *
+     * @param sequence - Screenshot sequence number
+     * @param uploadUrl - Pre-signed upload URL
+     * @param screenshotData - Screenshot data with base64 and format
+     * @returns True if upload successful, false otherwise
+     */
+    private _uploadSingleScreenshot;
+    /**
+     * Upload screenshot data to cloud using pre-signed URL
+     */
+    private _uploadScreenshotToCloud;
+    /**
+     * Delete local files after successful upload.
+     */
+    private _cleanupFiles;
+    /**
+     * Get unique identifier for this sink
+     */
+    getSinkType(): string;
+}
+//# sourceMappingURL=cloud-sink.d.ts.map

package/dist/tracing/cloud-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-sink.d.ts","sourceRoot":"","sources":["../../src/tracing/cloud-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,UAAU,EAAc,MAAM,SAAS,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAkBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAC,CAAkB;IAGjC,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,wBAAwB,CAAa;IAC7C,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,kBAAkB,CAAa;IAGvC,OAAO,CAAC,gBAAgB,CAAkB;IAE1C;;;;;;;;OAQG;gBAED,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,eAAe;IAkC1B;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAkB7B;;OAEG;YACW,cAAc;IAwC5B;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BpD;;OAEG;YACW,SAAS;IA+FvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IA4DlC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA8F9B;;;;OAIG;YACW,cAAc;IAsE5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;;OAKG;YACW,YAAY;IA+E1B;;OAEG;YACW,sBAAsB;IAyDpC;;OAEG;YACW,mBAAmB;IAuCjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IAwChC;;;;OAIG;YACW,4BAA4B;IAoD1C;;;;OAIG;YACW,mBAAmB;IAsCjC;;;;;OAKG;YACW,sBAAsB;IAwEpC;;;;;;;;;;OAUG;YACW,kBAAkB;IA0EhC;;;;;;;OAOG;YACW,uBAAuB;IAgCrC;;OAEG;YACW,wBAAwB;IA0CtC;;OAEG;YACW,aAAa;IAW3B;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}