catelog 1.0.1 → 1.0.3

package/dist/agent.js

@@ -1,40 +1,70 @@
-import { SecurityManager } from "./security.js";
-import { SSEWriter } from "./sse.js";
+import { randomUUID } from "node:crypto";
+import { SecurityManager, SecurityVerificationError } from "./security.js";
+import { SSEWriter, NoopStream } from "./sse.js";
 import { toJsonSchema, validateSchemaData } from "./schema.js";
+import { buildExecutionContext } from "./context.js";
+import { TelemetryReporter } from "./telemetry.js";
 import { PROTOCOL_VERSION, } from "./types.js";
 import { startAgentServer } from "./server.js";
-export class MarketplaceAgent {
+const asyncJobs = new Map();
+// Clean up old jobs periodically (keep for 1 hour)
+setInterval(() => {
+    const cutoff = Date.now() - 3_600_000;
+    for (const [id, job] of asyncJobs) {
+        if (job.createdAt < cutoff)
+            asyncJobs.delete(id);
+    }
+}, 300_000).unref();
+// ─────────────────────────────────────────────────
+//  CatelogAgent Class
+// ─────────────────────────────────────────────────
+export class CatelogAgent {
     id;
     name;
     version;
     description;
+    mode;
     capabilities;
     security;
     config;
     startTime;
+    telemetryReporter;
     constructor(config) {
         this.config = config;
         this.name = config.name;
         this.id = config.id || slugify(config.name);
         this.version = config.version || "1.0.0";
-        this.description = config.description || `Agent for ${this.name}`;
+        this.description = config.description || `Agent: ${this.name}`;
+        this.mode = config.mode || "sync";
         this.capabilities = {
             streaming: true,
-            delta_stream: false,
+            delta_stream: true,
             max_timeout_seconds: 300,
+            execution_modes: [this.mode],
             ...config.capabilities,
         };
-        this.security = new SecurityManager({ secret: config.secret });
+        this.security = new SecurityManager({
+            secret: config.secretKey,
+            publicKey: config.publicKey,
+        });
         this.startTime = Date.now();
+        this.telemetryReporter = new TelemetryReporter(config.telemetry);
     }
+    // ─────────────────────────────────────────────
+    //  GET /health — Ping probe for registration
+    // ─────────────────────────────────────────────
     getHealth() {
         return {
             status: "ready",
             protocol_version: PROTOCOL_VERSION,
             uptime_seconds: Math.floor((Date.now() - this.startTime) / 1000),
             environment_ready: true,
+            capabilities: this.capabilities,
         };
     }
+    // ─────────────────────────────────────────────
+    //  GET /schema — Agent Manifest
+    // ─────────────────────────────────────────────
     getManifest() {
         return {
             id: this.id,
@@ -43,121 +73,194 @@ export class MarketplaceAgent {
             description: this.description,
             protocol_version: PROTOCOL_VERSION,
             capabilities: this.capabilities,
-            input_schema: toJsonSchema(this.config.inputSchema, "InputSchema"),
-            output_schema: toJsonSchema(this.config.outputSchema, "OutputSchema"),
+            input_schema: this.config.inputSchema
+                ? toJsonSchema(this.config.inputSchema, "InputSchema")
+                : { type: "object", additionalProperties: true },
+            output_schema: this.config.outputSchema
+                ? toJsonSchema(this.config.outputSchema, "OutputSchema")
+                : { type: "object", additionalProperties: true },
         };
     }
-    serve(portOrOptions) {
+    // ─────────────────────────────────────────────
+    //  .listen(port) — Start the agent server
+    // ─────────────────────────────────────────────
+    listen(portOrOptions) {
         const opts = typeof portOrOptions === "number" ? { port: portOrOptions } : portOrOptions;
         return startAgentServer(this, opts);
     }
+    /** Alias for backward compat */
+    serve(portOrOptions) {
+        return this.listen(portOrOptions);
+    }
+    // ─────────────────────────────────────────────
+    //  Request Router
+    // ─────────────────────────────────────────────
     async handleRequest(req, res) {
         const method = req.method?.toUpperCase() || "GET";
         const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
         const pathname = url.pathname;
-        // Enable CORS for testing & browser callers
+        // CORS
         res.setHeader("Access-Control-Allow-Origin", "*");
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, X-Marketplace-Protocol, X-Marketplace-Timestamp, X-Marketplace-Nonce, X-Marketplace-Run-Id, X-Marketplace-Signature");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization, " +
+            "X-Marketplace-Protocol, X-Marketplace-Timestamp, X-Marketplace-Nonce, " +
+            "X-Marketplace-Run-Id, X-Marketplace-Signature");
         if (method === "OPTIONS") {
             res.writeHead(204);
             res.end();
             return;
         }
         try {
+            // Health probe
             if (pathname === "/health" && method === "GET") {
-                this.writeJsonResponse(res, 200, this.getHealth());
+                this.writeJson(res, 200, this.getHealth());
                 return;
             }
+            // Schema manifest
             if (pathname === "/schema" && method === "GET") {
-                this.writeJsonResponse(res, 200, this.getManifest());
+                this.writeJson(res, 200, this.getManifest());
                 return;
             }
+            // Execute
             if (pathname === "/execute" && method === "POST") {
                 await this.handleExecute(req, res);
                 return;
             }
-            this.writeJsonResponse(res, 404, {
-                error: {
-                    code: "NOT_FOUND",
-                    message: `Endpoint ${method} ${pathname} not found`,
-                    retryable: false,
-                },
+            // Async job polling: GET /tasks/:id
+            if (pathname.startsWith("/tasks/") && method === "GET") {
+                const jobId = pathname.slice(7); // Remove "/tasks/"
+                this.handleTaskPoll(res, jobId);
+                return;
+            }
+            this.writeJson(res, 404, {
+                error: { code: "NOT_FOUND", message: `${method} ${pathname} not found`, retryable: false },
             });
         }
         catch (err) {
             const error = normalizeError(err);
-            this.writeJsonResponse(res, 500, {
-                error,
-            });
+            this.writeJson(res, 500, { error });
         }
     }
+    // ─────────────────────────────────────────────
+    //  POST /execute — Core Execution Handler
+    // ─────────────────────────────────────────────
     async handleExecute(req, res) {
         const rawBody = await readBody(req);
         const headers = req.headers;
         const path = req.url || "/execute";
         const method = req.method || "POST";
-        // 1. Security & Signature verification
+        // ── Authentication (Dual-Mode: Bearer / HMAC / Dev) ──
         let authInfo;
         try {
-            authInfo = this.security.verifyRequest({
-                method,
-                path,
-                headers,
-                rawBody,
-            });
+            authInfo = this.security.authenticateRequest({ method, path, headers, rawBody });
         }
         catch (err) {
-            if (err && typeof err === "object" && "code" in err && "statusCode" in err) {
-                const secErr = err;
-                this.writeJsonResponse(res, secErr.statusCode, {
-                    error: {
-                        code: secErr.code,
-                        message: secErr.message,
-                        retryable: false,
-                    },
+            if (err instanceof SecurityVerificationError) {
+                this.writeJson(res, err.statusCode, {
+                    error: { code: err.code, message: err.message, retryable: false },
                 });
                 return;
             }
             throw err;
         }
-        // Parse request body
+        // ── Parse body ──
         let payload;
         try {
-            payload = rawBody.length > 0 ? JSON.parse(rawBody.toString("utf8")) : {};
+            payload = rawBody.length > 0 ? JSON.parse(rawBody.toString("utf8")) : { input: {} };
         }
         catch {
-            this.writeJsonResponse(res, 400, {
-                error: {
-                    code: "INVALID_INPUT",
-                    message: "Malformed JSON request body",
-                    retryable: false,
-                },
+            this.writeJson(res, 400, {
+                error: { code: "INVALID_INPUT", message: "Malformed JSON body", retryable: false },
             });
             return;
         }
         const runId = payload.run_id || authInfo.runId;
+        const inputBytes = rawBody.length;
+        // ── Optional input validation (only if schema provided) ──
+        let validatedInput;
+        if (this.config.inputSchema) {
+            const validation = validateSchemaData(this.config.inputSchema, payload.input);
+            if (!validation.success) {
+                this.writeJson(res, 400, {
+                    run_id: runId,
+                    status: "failed",
+                    duration_ms: 0,
+                    error: {
+                        code: "INVALID_INPUT",
+                        message: `Validation failed: ${validation.errors.join("; ")}`,
+                        retryable: false,
+                        details: { validationErrors: validation.errors },
+                    },
+                });
+                return;
+            }
+            validatedInput = validation.data;
+        }
+        else {
+            // No schema — accept any input
+            validatedInput = (payload.input ?? {});
+        }
         this.security.markRunStarted(runId);
-        // 2. Pre-Execution Schema Validation
-        const validation = validateSchemaData(this.config.inputSchema, payload.input);
-        if (!validation.success) {
-            this.security.markRunCompleted(runId);
-            this.writeJsonResponse(res, 400, {
-                run_id: runId,
-                status: "failed",
-                duration_ms: 0,
-                error: {
-                    code: "INVALID_INPUT",
-                    message: `Input validation failed: ${validation.errors.join("; ")}`,
-                    retryable: false,
-                    details: { validationErrors: validation.errors },
-                },
+        // ── Execution Mode Dispatch ──
+        if (this.mode === "async") {
+            await this.executeAsync(runId, validatedInput, payload, inputBytes, res);
+        }
+        else {
+            // sync & conversational both stream via SSE or batch JSON
+            await this.executeSyncOrConversational(runId, validatedInput, payload, inputBytes, req, res);
+        }
+    }
+    // ── Async Mode: Return 202 immediately, run in background ──
+    async executeAsync(runId, input, payload, inputBytes, res) {
+        const job = {
+            runId,
+            status: "working",
+            createdAt: Date.now(),
+        };
+        asyncJobs.set(runId, job);
+        // Respond immediately with 202
+        this.writeJson(res, 202, {
+            run_id: runId,
+            status: "working",
+            poll_url: `/tasks/${runId}`,
+        });
+        // Execute in background (fire-and-forget from HTTP perspective)
+        const startTs = Date.now();
+        const noopStream = new NoopStream();
+        const abortController = new AbortController();
+        try {
+            const { ctx, telemetryCollector } = buildExecutionContext({
+                runId,
+                input,
+                stream: noopStream,
+                signal: abortController.signal,
+                metadata: payload.metadata,
+                deadlineMs: payload.deadline_ms,
+                resumeToken: payload.resume_token,
+                inputBytes,
             });
-            return;
+            const rawResult = await this.config.execute(ctx);
+            const durationMs = Date.now() - startTs;
+            const result = this.normalizeExecuteResult(rawResult);
+            job.status = "completed";
+            job.output = result.output;
+            job.durationMs = durationMs;
+            job.telemetry = telemetryCollector.finalize(result.telemetry);
+        }
+        catch (err) {
+            job.status = "failed";
+            job.error = normalizeError(err);
+            job.durationMs = Date.now() - startTs;
+        }
+        finally {
+            this.security.markRunCompleted(runId);
         }
-        const startTimestamp = Date.now();
+    }
+    // ── Sync / Conversational Mode ──
+    async executeSyncOrConversational(runId, input, payload, inputBytes, req, res) {
+        const startTs = Date.now();
         const acceptsSse = req.headers.accept?.includes("text/event-stream") ?? true;
-        // Setup deadline timeout if specified
+        // Abort controller for deadline / disconnect
         const abortController = new AbortController();
         let timeoutTimer;
         if (payload.deadline_ms && payload.deadline_ms > Date.now()) {
@@ -167,89 +270,205 @@ export class MarketplaceAgent {
             }, waitTime);
         }
         if (acceptsSse) {
-            // Streaming SSE Response Mode
-            const sseWriter = new SSEWriter(runId, res, {
-                onClientDisconnect: () => {
-                    abortController.abort(new Error("CLIENT_DISCONNECTED"));
-                },
-            });
-            // Forward abort signal
-            sseWriter.signal.addEventListener("abort", () => {
-                abortController.abort(sseWriter.signal.reason);
-            });
-            // Send initial run.started event
-            sseWriter.sendRunStarted();
-            try {
-                const result = await this.config.execute({
-                    runId,
-                    input: validation.data,
-                    stream: sseWriter,
-                    signal: abortController.signal,
-                    metadata: payload.metadata,
-                    deadlineMs: payload.deadline_ms,
-                });
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                const durationMs = Date.now() - startTimestamp;
+            await this.executeWithSSE(runId, input, payload, inputBytes, startTs, res, abortController, timeoutTimer);
+        }
+        else {
+            await this.executeWithJSON(runId, input, payload, inputBytes, startTs, res, abortController, timeoutTimer);
+        }
+    }
+    // ── SSE Streaming Execution ──
+    async executeWithSSE(runId, input, payload, inputBytes, startTs, res, abortController, timeoutTimer) {
+        const sseWriter = new SSEWriter(runId, res, {
+            onClientDisconnect: () => abortController.abort(new Error("CLIENT_DISCONNECTED")),
+        });
+        sseWriter.signal.addEventListener("abort", () => {
+            abortController.abort(sseWriter.signal.reason);
+        });
+        // Emit initial working status
+        sseWriter.sendTaskStatus("working");
+        const { ctx, telemetryCollector } = buildExecutionContext({
+            runId,
+            input,
+            stream: sseWriter,
+            signal: abortController.signal,
+            metadata: payload.metadata,
+            deadlineMs: payload.deadline_ms,
+            resumeToken: payload.resume_token,
+            inputBytes,
+        });
+        try {
+            const rawResult = await this.config.execute(ctx);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            const durationMs = Date.now() - startTs;
+            // Check if result is a needInput request
+            if (this.isNeedInputResult(rawResult)) {
+                const needInput = rawResult;
+                const resumeToken = `resume_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+                sseWriter.sendTaskInputRequired(needInput.prompt, resumeToken, needInput.schema);
+                this.reportTelemetry(runId, "input-required", telemetryCollector.finalize(), durationMs);
                 this.security.markRunCompleted(runId);
-                sseWriter.sendRunSucceeded(result.output, durationMs, result.telemetry);
+                return;
             }
-            catch (err) {
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                const durationMs = Date.now() - startTimestamp;
-                this.security.markRunCompleted(runId);
+            const result = this.normalizeExecuteResult(rawResult);
+            const outputBytes = JSON.stringify(result.output).length;
+            const telemetry = telemetryCollector.finalize({
+                ...result.telemetry,
+                duration_ms: durationMs,
+                output_bytes: outputBytes,
+                chunks_streamed: sseWriter.chunksStreamed,
+            });
+            res.setHeader("X-Catelog-Duration-Ms", String(durationMs));
+            sseWriter.sendTaskCompleted(result.output, durationMs, telemetry);
+            this.reportTelemetry(runId, "completed", telemetry, durationMs);
+        }
+        catch (err) {
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            const durationMs = Date.now() - startTs;
+            if (abortController.signal.aborted) {
+                sseWriter.sendTaskCanceled(durationMs);
+                this.reportTelemetry(runId, "canceled", telemetryCollector.finalize({ duration_ms: durationMs }), durationMs);
+            }
+            else {
                 const error = normalizeError(err);
-                sseWriter.sendRunFailed(error, durationMs);
+                sseWriter.sendTaskFailed(error, durationMs);
+                this.reportTelemetry(runId, "failed", telemetryCollector.finalize({ duration_ms: durationMs }), durationMs);
             }
         }
-        else {
-            // Batch JSON Mode
-            try {
-                const noopStream = {
-                    step: () => { },
-                    delta: () => { },
-                    emit: () => { },
-                    isClosed: () => false,
-                };
-                const result = await this.config.execute({
-                    runId,
-                    input: validation.data,
-                    stream: noopStream,
-                    signal: abortController.signal,
-                    metadata: payload.metadata,
-                    deadlineMs: payload.deadline_ms,
-                });
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                const durationMs = Date.now() - startTimestamp;
-                this.security.markRunCompleted(runId);
-                const response = {
-                    run_id: runId,
-                    status: "succeeded",
-                    duration_ms: durationMs,
-                    output: result.output,
-                    telemetry: result.telemetry,
-                };
-                this.writeJsonResponse(res, 200, response);
-            }
-            catch (err) {
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                const durationMs = Date.now() - startTimestamp;
+        finally {
+            this.security.markRunCompleted(runId);
+        }
+    }
+    // ── Batch JSON Execution ──
+    async executeWithJSON(runId, input, payload, inputBytes, startTs, res, abortController, timeoutTimer) {
+        const noopStream = new NoopStream();
+        const { ctx, telemetryCollector } = buildExecutionContext({
+            runId,
+            input,
+            stream: noopStream,
+            signal: abortController.signal,
+            metadata: payload.metadata,
+            deadlineMs: payload.deadline_ms,
+            resumeToken: payload.resume_token,
+            inputBytes,
+        });
+        try {
+            const rawResult = await this.config.execute(ctx);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            const durationMs = Date.now() - startTs;
+            // Check needInput
+            if (this.isNeedInputResult(rawResult)) {
+                const needInput = rawResult;
+                const resumeToken = `resume_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
                 this.security.markRunCompleted(runId);
-                const error = normalizeError(err);
-                const response = {
+                this.writeJson(res, 200, {
                     run_id: runId,
-                    status: "failed",
+                    status: "input-required",
                     duration_ms: durationMs,
-                    error,
-                };
-                this.writeJsonResponse(res, 200, response);
+                    prompt: needInput.prompt,
+                    input_schema: needInput.schema,
+                    resume_token: resumeToken,
+                });
+                return;
             }
+            const result = this.normalizeExecuteResult(rawResult);
+            const outputBytes = JSON.stringify(result.output).length;
+            const telemetry = telemetryCollector.finalize({
+                ...result.telemetry,
+                duration_ms: durationMs,
+                output_bytes: outputBytes,
+                chunks_streamed: noopStream.chunksStreamed,
+            });
+            this.security.markRunCompleted(runId);
+            res.setHeader("X-Catelog-Duration-Ms", String(durationMs));
+            const response = {
+                run_id: runId,
+                status: "completed",
+                duration_ms: durationMs,
+                output: result.output,
+                telemetry,
+            };
+            this.writeJson(res, 200, response);
+            this.reportTelemetry(runId, "completed", telemetry, durationMs);
+        }
+        catch (err) {
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            const durationMs = Date.now() - startTs;
+            this.security.markRunCompleted(runId);
+            const error = normalizeError(err);
+            const response = {
+                run_id: runId,
+                status: abortController.signal.aborted ? "canceled" : "failed",
+                duration_ms: durationMs,
+                error,
+            };
+            this.writeJson(res, 200, response);
+        }
+    }
+    // ── Async Job Polling ──
+    handleTaskPoll(res, jobId) {
+        const job = asyncJobs.get(jobId);
+        if (!job) {
+            this.writeJson(res, 404, {
+                error: { code: "NOT_FOUND", message: `No task found: ${jobId}`, retryable: false },
+            });
+            return;
+        }
+        if (job.status === "working") {
+            this.writeJson(res, 200, {
+                run_id: job.runId,
+                status: "working",
+                elapsed_ms: Date.now() - job.createdAt,
+            });
+        }
+        else if (job.status === "completed") {
+            this.writeJson(res, 200, {
+                run_id: job.runId,
+                status: "completed",
+                duration_ms: job.durationMs,
+                output: job.output,
+                telemetry: job.telemetry,
+            });
+        }
+        else {
+            this.writeJson(res, 200, {
+                run_id: job.runId,
+                status: "failed",
+                duration_ms: job.durationMs,
+                error: job.error,
+            });
         }
     }
-    writeJsonResponse(res, status, data) {
+    // ── Helpers ──
+    /**
+     * Normalize the developer's return value into our standard result shape.
+     * Supports:
+     * - { output: T, telemetry?: ... } → standard result
+     * - Any other value → treated as the output directly
+     */
+    normalizeExecuteResult(raw) {
+        if (raw && typeof raw === "object" && "output" in raw) {
+            return raw;
+        }
+        // The developer just returned a plain object — that IS the output
+        return { output: raw };
+    }
+    isNeedInputResult(value) {
+        return value && typeof value === "object" && value[Symbol.for("catelog.needInput")] === true;
+    }
+    reportTelemetry(runId, status, telemetry, durationMs) {
+        this.telemetryReporter.report({
+            agentId: this.id,
+            runId,
+            status,
+            telemetry: { ...telemetry, duration_ms: durationMs },
+            timestamp: Date.now(),
+        });
+    }
+    writeJson(res, status, data) {
         if (res.writableEnded)
             return;
         const body = JSON.stringify(data);
@@ -260,12 +479,22 @@ export class MarketplaceAgent {
         res.end(body);
     }
 }
-/**
- * Convenience builder function for creating a compliant Marketplace Agent
- */
+// ─────────────────────────────────────────────────
+//  Factory Function
+// ─────────────────────────────────────────────────
+/** Create a new CatelogAgent */
+export function createAgent(config) {
+    return new CatelogAgent(config);
+}
+/** Legacy alias */
 export function createMarketplaceAgent(config) {
-    return new MarketplaceAgent(config);
+    return new CatelogAgent(config);
 }
+// Backward compat alias
+export { CatelogAgent as MarketplaceAgent };
+// ─────────────────────────────────────────────────
+//  Utilities
+// ─────────────────────────────────────────────────
 function slugify(text) {
     return text
         .toLowerCase()
@@ -277,26 +506,16 @@ function slugify(text) {
 function normalizeError(err, defaultCode = "INTERNAL_CRASH") {
     if (err instanceof Error) {
         if (err.name === "AbortError" || err.message === "EXECUTION_TIMEOUT") {
-            return {
-                code: "EXECUTION_TIMEOUT",
-                message: "Execution exceeded allowed deadline or timeout",
-                retryable: true,
-            };
+            return { code: "EXECUTION_TIMEOUT", message: "Exceeded deadline or timeout", retryable: true };
+        }
+        if (err.message === "CLIENT_DISCONNECTED") {
+            return { code: "TASK_CANCELED", message: "Client disconnected", retryable: false };
         }
-        // Check for standard error codes attached to error object
         const code = err.code || defaultCode;
         const retryable = err.retryable ?? false;
-        return {
-            code,
-            message: err.message,
-            retryable,
-        };
+        return { code, message: err.message, retryable };
     }
-    return {
-        code: defaultCode,
-        message: String(err),
-        retryable: false,
-    };
+    return { code: defaultCode, message: String(err), retryable: false };
 }
 async function readBody(req) {
     return new Promise((resolve, reject) => {