@prefactor/core 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,14 +1,101 @@
+// packages/core/src/agent/instance-manager.ts
+import { isDeepStrictEqual } from "node:util";
+
+// packages/core/src/agent/schema-registry.ts
+class SchemaRegistry {
+  schemas = new Map;
+  register(schema) {
+    this.schemas.set(this.getKey(schema.schemaName, schema.schemaIdentifier), schema);
+  }
+  has(schemaName, schemaIdentifier) {
+    return this.schemas.has(this.getKey(schemaName, schemaIdentifier));
+  }
+  get(schemaName, schemaIdentifier) {
+    return this.schemas.get(this.getKey(schemaName, schemaIdentifier));
+  }
+  getKey(schemaName, schemaIdentifier) {
+    return `${schemaName}@${schemaIdentifier}`;
+  }
+}
+
+// packages/core/src/agent/instance-manager.ts
+var orderInsensitiveArrayKeys = new Set(["required", "enum", "oneOf", "allOf", "anyOf", "type"]);
+var stableStringify = (value) => JSON.stringify(value) ?? "undefined";
+var normalizeSchema = (value, arrayKey) => {
+  if (Array.isArray(value)) {
+    const normalizedItems = value.map((item) => normalizeSchema(item));
+    if (arrayKey && orderInsensitiveArrayKeys.has(arrayKey)) {
+      return normalizedItems.map((item) => ({ item, key: stableStringify(item) })).sort((left, right) => left.key.localeCompare(right.key)).map(({ item }) => item);
+    }
+    return normalizedItems;
+  }
+  if (value && typeof value === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto === Object.prototype || proto === null) {
+      const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+      const normalized = {};
+      for (const [key, entryValue] of entries) {
+        normalized[key] = normalizeSchema(entryValue, key);
+      }
+      return normalized;
+    }
+  }
+  return value;
+};
+
+class AgentInstanceManager {
+  queue;
+  options;
+  schemaRegistry = new SchemaRegistry;
+  constructor(queue, options) {
+    this.queue = queue;
+    this.options = options;
+  }
+  registerSchema(schema) {
+    if (this.schemaRegistry.has(this.options.schemaName, this.options.schemaIdentifier)) {
+      const existing = this.schemaRegistry.get(this.options.schemaName, this.options.schemaIdentifier);
+      if (existing && !isDeepStrictEqual(normalizeSchema(existing.schema), normalizeSchema(schema))) {
+        console.warn(`Schema ${this.options.schemaName}@${this.options.schemaIdentifier} is already registered with a different payload. Ignoring registration.`);
+      }
+      return;
+    }
+    const registration = {
+      schemaName: this.options.schemaName,
+      schemaIdentifier: this.options.schemaIdentifier,
+      schema
+    };
+    this.schemaRegistry.register(registration);
+    this.queue.enqueue({ type: "schema_register", data: registration });
+  }
+  startInstance(options = {}) {
+    if (!this.options.allowUnregisteredSchema && !this.schemaRegistry.has(this.options.schemaName, this.options.schemaIdentifier)) {
+      console.warn(`Schema ${this.options.schemaName}@${this.options.schemaIdentifier} must be registered before starting an agent instance.`);
+      return;
+    }
+    const startData = {
+      ...options,
+      schemaName: this.options.schemaName,
+      schemaIdentifier: this.options.schemaIdentifier
+    };
+    this.queue.enqueue({ type: "agent_start", data: startData });
+  }
+  finishInstance() {
+    this.queue.enqueue({ type: "agent_finish", data: {} });
+  }
+}
 // packages/core/src/config.ts
 import { z } from "zod";
 var HttpTransportConfigSchema = z.object({
   apiUrl: z.string().url(),
   apiToken: z.string().min(1),
   agentId: z.string().optional(),
-  agentVersion: z.string().optional(),
+  agentIdentifier: z.string().default("v1.0.0"),
   agentName: z.string().optional(),
   agentDescription: z.string().optional(),
+  schemaName: z.string().optional(),
+  schemaIdentifier: z.string().optional(),
   agentSchema: z.record(z.unknown()).optional(),
-  agentSchemaVersion: z.string().optional(),
+  agentSchemaIdentifier: z.string().optional(),
   skipSchema: z.boolean().default(false),
   requestTimeout: z.number().positive().default(30000),
   connectTimeout: z.number().positive().default(1e4),
@@ -21,11 +108,13 @@ var PartialHttpConfigSchema = z.object({
   apiUrl: z.string().url(),
   apiToken: z.string().min(1),
   agentId: z.string().optional(),
-  agentVersion: z.string().optional(),
+  agentIdentifier: z.string().optional(),
   agentName: z.string().optional(),
   agentDescription: z.string().optional(),
+  schemaName: z.string().optional(),
+  schemaIdentifier: z.string().optional(),
   agentSchema: z.record(z.unknown()).optional(),
-  agentSchemaVersion: z.string().optional(),
+  agentSchemaIdentifier: z.string().optional(),
   skipSchema: z.boolean().optional(),
   requestTimeout: z.number().positive().optional(),
   connectTimeout: z.number().positive().optional(),
@@ -55,24 +144,75 @@ function createConfig(options) {
   };
   return ConfigSchema.parse(config);
 }
+// packages/core/src/create-core.ts
+import { extractPartition } from "@prefactor/pfid";
+
+// packages/core/src/queue/in-memory.ts
+class InMemoryQueue {
+  items = [];
+  enqueue(item) {
+    this.items.push(item);
+  }
+  dequeueBatch(maxItems) {
+    if (this.items.length === 0)
+      return [];
+    return this.items.splice(0, maxItems);
+  }
+  size() {
+    return this.items.length;
+  }
+  async flush() {
+    return;
+  }
+}
+
+// packages/core/src/tracing/tracer.ts
+import { generate, generatePartition } from "@prefactor/pfid";
+
 // packages/core/src/tracing/context.ts
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage, AsyncResource } from "node:async_hooks";
 var spanStorage = new AsyncLocalStorage;
 
 class SpanContext {
   static getCurrent() {
-    return spanStorage.getStore();
+    const stack = spanStorage.getStore() ?? [];
+    return stack[stack.length - 1];
+  }
+  static getStack() {
+    return [...spanStorage.getStore() ?? []];
+  }
+  static enter(span) {
+    const stack = [...spanStorage.getStore() ?? [], span];
+    spanStorage.enterWith(stack);
+  }
+  static exit() {
+    const stack = [...spanStorage.getStore() ?? []];
+    stack.pop();
+    spanStorage.enterWith(stack);
   }
   static run(span, fn) {
-    return spanStorage.run(span, fn);
+    const stack = spanStorage.getStore() ?? [];
+    const resource = new AsyncResource("SpanContext.run");
+    try {
+      return resource.runInAsyncScope(() => spanStorage.run([...stack, span], fn));
+    } finally {
+      resource.emitDestroy();
+    }
   }
   static async runAsync(span, fn) {
-    return spanStorage.run(span, fn);
+    const stack = spanStorage.getStore() ?? [];
+    const resource = new AsyncResource("SpanContext.runAsync");
+    try {
+      return await resource.runInAsyncScope(() => spanStorage.run([...stack, span], fn));
+    } finally {
+      resource.emitDestroy();
+    }
   }
   static clear() {
     spanStorage.disable();
   }
 }
+
 // packages/core/src/tracing/span.ts
 var SpanType;
 ((SpanType2) => {
@@ -82,27 +222,53 @@ var SpanType;
   SpanType2["CHAIN"] = "chain";
   SpanType2["RETRIEVER"] = "retriever";
 })(SpanType ||= {});
+var DEFAULT_AGENT_SCHEMA = {
+  external_identifier: "1.0.0",
+  span_schemas: {
+    agent: {
+      type: "object",
+      properties: { type: { type: "string", const: "agent" } }
+    },
+    llm: {
+      type: "object",
+      properties: { type: { type: "string", const: "llm" } }
+    },
+    tool: {
+      type: "object",
+      properties: { type: { type: "string", const: "tool" } }
+    },
+    chain: {
+      type: "object",
+      properties: { type: { type: "string", const: "chain" } }
+    },
+    retriever: {
+      type: "object",
+      properties: { type: { type: "string", const: "retriever" } }
+    }
+  }
+};
 var SpanStatus;
 ((SpanStatus2) => {
   SpanStatus2["RUNNING"] = "running";
   SpanStatus2["SUCCESS"] = "success";
   SpanStatus2["ERROR"] = "error";
 })(SpanStatus ||= {});
+
 // packages/core/src/tracing/tracer.ts
-import { generate, generatePartition } from "@prefactor/pfid";
 class Tracer {
-  transport;
+  queue;
   partition;
-  constructor(transport, partition) {
-    this.transport = transport;
+  constructor(queue, partition) {
+    this.queue = queue;
     this.partition = partition ?? generatePartition();
   }
   startSpan(options) {
+    const parentSpan = SpanContext.getCurrent();
     const spanId = generate(this.partition);
-    const traceId = options.traceId ?? generate(this.partition);
+    const traceId = parentSpan?.traceId ?? generate(this.partition);
     const span = {
       spanId,
-      parentSpanId: options.parentSpanId ?? null,
+      parentSpanId: parentSpan?.spanId ?? null,
       traceId,
       name: options.name,
       spanType: options.spanType,
@@ -116,17 +282,18 @@ class Tracer {
       metadata: options.metadata ?? {},
       tags: options.tags ?? []
     };
-    if (options.spanType === "agent") {
+    if (options.spanType === "agent" /* AGENT */) {
       try {
-        this.transport.emit(span);
+        this.queue.enqueue({ type: "span_end", data: span });
       } catch (error) {
-        console.error("Failed to emit agent span:", error);
+        console.error("Failed to enqueue agent span:", error);
       }
     }
     return span;
   }
   endSpan(span, options) {
-    span.endTime = Date.now();
+    const endTime = Date.now();
+    span.endTime = endTime;
     span.outputs = options?.outputs ?? null;
     span.tokenUsage = options?.tokenUsage ?? null;
     if (options?.error) {
@@ -140,37 +307,24 @@ class Tracer {
       span.status = "success" /* SUCCESS */;
     }
     try {
-      if (span.spanType === "agent") {
-        this.transport.finishSpan(span.spanId, span.endTime);
+      if (span.spanType === "agent" /* AGENT */) {
+        this.queue.enqueue({ type: "span_finish", data: { spanId: span.spanId, endTime } });
       } else {
-        this.transport.emit(span);
+        this.queue.enqueue({ type: "span_end", data: span });
       }
     } catch (error) {
-      console.error("Failed to emit/finish span:", error);
-    }
-  }
-  startAgentInstance() {
-    try {
-      this.transport.startAgentInstance();
-    } catch (error) {
-      console.error("Failed to start agent instance:", error);
-    }
-  }
-  finishAgentInstance() {
-    try {
-      this.transport.finishAgentInstance();
-    } catch (error) {
-      console.error("Failed to finish agent instance:", error);
+      console.error("Failed to enqueue span action:", error);
     }
   }
   async close() {
     try {
-      await this.transport.close();
+      await this.queue.flush();
     } catch (error) {
-      console.error("Failed to close transport:", error);
+      console.error("Failed to flush queue:", error);
     }
   }
 }
+
 // packages/core/src/utils/logging.ts
 class Logger {
   namespace;
@@ -223,73 +377,76 @@ var logger = getLogger("http-transport");
 
 class HttpTransport {
   config;
-  queue = [];
-  processing = false;
   closed = false;
   agentInstanceId = null;
   spanIdMap = new Map;
+  pendingFinishes = new Map;
   constructor(config) {
     this.config = config;
-    this.startProcessing();
-  }
-  emit(span) {
-    if (this.closed) {
-      return;
-    }
-    this.queue.push({ type: "span", data: span });
-  }
-  finishSpan(spanId, endTime) {
-    if (this.closed) {
-      return;
-    }
-    const timestamp = new Date(endTime).toISOString();
-    this.queue.push({ type: "finish_span", data: { spanId, timestamp } });
-  }
-  startAgentInstance() {
-    if (this.closed) {
-      return;
-    }
-    this.queue.push({ type: "start_agent", data: null });
   }
-  finishAgentInstance() {
-    if (this.closed) {
+  async processBatch(items) {
+    if (this.closed || items.length === 0) {
       return;
     }
-    this.queue.push({ type: "finish_agent", data: null });
-  }
-  async startProcessing() {
-    this.processing = true;
-    while (!this.closed || this.queue.length > 0) {
-      if (this.queue.length === 0) {
-        await new Promise((resolve) => setTimeout(resolve, 100));
-        continue;
+    for (const item of items) {
+      if (item.type === "schema_register") {
+        this.config.agentSchema = item.data.schema;
+        this.config.agentSchemaIdentifier = item.data.schemaIdentifier;
+        this.config.schemaName = item.data.schemaName;
+        this.config.schemaIdentifier = item.data.schemaIdentifier;
       }
-      const item = this.queue.shift();
-      if (!item)
-        continue;
+    }
+    for (const item of items) {
       try {
-        if (!this.agentInstanceId && item.type !== "start_agent") {
-          await this.ensureAgentRegistered();
-        }
         switch (item.type) {
-          case "span":
-            await this.sendSpan(item.data);
-            break;
-          case "finish_span":
-            await this.finishSpanHttp(item.data);
+          case "schema_register":
             break;
-          case "start_agent":
+          case "agent_start":
+            this.config.agentId = item.data.agentId;
+            if (item.data.agentIdentifier !== undefined)
+              this.config.agentIdentifier = item.data.agentIdentifier;
+            this.config.agentName = item.data.agentName;
+            this.config.agentDescription = item.data.agentDescription;
             await this.startAgentInstanceHttp();
             break;
-          case "finish_agent":
+          case "agent_finish":
             await this.finishAgentInstanceHttp();
             break;
+          case "span_end":
+            if (!this.agentInstanceId) {
+              await this.ensureAgentRegistered();
+            }
+            await this.sendSpan(item.data);
+            break;
+          case "span_finish": {
+            const spanId = item.data.spanId;
+            const backendSpanId = this.spanIdMap.get(spanId);
+            if (backendSpanId) {
+              const timestamp = new Date(item.data.endTime).toISOString();
+              await this.finishSpanHttp({ spanId, timestamp });
+            } else {
+              this.pendingFinishes.set(spanId, item.data.endTime);
+            }
+            break;
+          }
         }
       } catch (error) {
-        logger.error("Error processing queue item:", error);
+        logger.error("Error processing batch item:", error);
       }
     }
-    this.processing = false;
+  }
+  async processPendingFinishes(spanId) {
+    const pendingEndTime = this.pendingFinishes.get(spanId);
+    if (!pendingEndTime) {
+      return;
+    }
+    try {
+      const timestamp = new Date(pendingEndTime).toISOString();
+      await this.finishSpanHttp({ spanId, timestamp });
+      this.pendingFinishes.delete(spanId);
+    } catch (error) {
+      logger.error("Error processing pending span finish:", error);
+    }
   }
   async sendSpan(span, retry = 0) {
     const url = `${this.config.apiUrl}/api/v1/agent_spans`;
@@ -309,6 +466,7 @@ class HttpTransport {
         const backendSpanId = data?.details?.id;
         if (backendSpanId) {
           this.spanIdMap.set(span.spanId, backendSpanId);
+          await this.processPendingFinishes(span.spanId);
         }
         return;
       }
@@ -370,31 +528,7 @@ class HttpTransport {
     };
   }
   getDefaultSchema() {
-    return {
-      external_identifier: "1.0.0",
-      span_schemas: {
-        agent: {
-          type: "object",
-          properties: { type: { type: "string", const: "agent" } }
-        },
-        llm: {
-          type: "object",
-          properties: { type: { type: "string", const: "llm" } }
-        },
-        tool: {
-          type: "object",
-          properties: { type: { type: "string", const: "tool" } }
-        },
-        chain: {
-          type: "object",
-          properties: { type: { type: "string", const: "chain" } }
-        },
-        retriever: {
-          type: "object",
-          properties: { type: { type: "string", const: "retriever" } }
-        }
-      }
-    };
+    return DEFAULT_AGENT_SCHEMA;
   }
   async ensureAgentRegistered() {
     if (this.agentInstanceId) {
@@ -404,9 +538,9 @@ class HttpTransport {
     const payload = {};
     if (this.config.agentId)
       payload.agent_id = this.config.agentId;
-    if (this.config.agentVersion) {
+    if (this.config.agentIdentifier) {
       payload.agent_version = {
-        external_identifier: this.config.agentVersion,
+        external_identifier: this.config.agentIdentifier,
         name: this.config.agentName || "Agent",
         description: this.config.agentDescription || ""
       };
@@ -416,10 +550,10 @@ class HttpTransport {
     } else if (this.config.agentSchema) {
       logger.debug("Using custom agent schema");
       payload.agent_schema_version = this.config.agentSchema;
-    } else if (this.config.agentSchemaVersion) {
-      logger.debug(`Using schema version: ${this.config.agentSchemaVersion}`);
+    } else if (this.config.agentSchemaIdentifier) {
+      logger.debug(`Using schema version: ${this.config.agentSchemaIdentifier}`);
       payload.agent_schema_version = {
-        external_identifier: this.config.agentSchemaVersion
+        external_identifier: this.config.agentSchemaIdentifier
       };
     } else {
       logger.debug("Using default hardcoded schema (v1.0.0)");
@@ -492,6 +626,7 @@ class HttpTransport {
     } catch (error) {
       logger.error("Error finishing agent instance:", error);
     }
+    this.agentInstanceId = null;
   }
   async finishSpanHttp(data) {
     const backendSpanId = this.spanIdMap.get(data.spanId);
@@ -519,16 +654,13 @@ class HttpTransport {
   }
   async close() {
     this.closed = true;
-    const timeout = 1e4;
-    const start = Date.now();
-    while (this.processing && Date.now() - start < timeout) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
-    }
-    if (this.processing) {
-      logger.warn("Transport closed with pending queue items");
+    if (this.pendingFinishes.size > 0) {
+      logger.warn(`Transport closed with ${this.pendingFinishes.size} pending span finish(es) that could not be processed`);
+      this.pendingFinishes.clear();
     }
   }
 }
+
 // packages/core/src/utils/serialization.ts
 function truncateString(value, maxLength) {
   if (value.length <= maxLength) {
@@ -567,33 +699,153 @@ function serializeValue(value, maxLength = 1e4) {
 class StdioTransport {
   closed = false;
   writeLock = Promise.resolve();
-  emit(span) {
-    if (this.closed) {
+  async processBatch(items) {
+    if (this.closed || items.length === 0) {
       return;
     }
     this.writeLock = this.writeLock.then(async () => {
-      try {
-        const serialized = serializeValue(span);
-        const json = JSON.stringify(serialized);
-        await Bun.write(Bun.stdout, `${json}
+      for (const item of items) {
+        try {
+          const serialized = serializeValue(item);
+          const json = JSON.stringify(serialized);
+          await Bun.write(Bun.stdout, `${json}
 `);
-      } catch (error) {
-        console.error("Failed to emit span to stdout:", error);
+        } catch (error) {
+          console.error("Failed to emit queue action to stdout:", error);
+        }
       }
     });
+    await this.writeLock;
   }
-  finishSpan() {}
-  startAgentInstance() {}
-  finishAgentInstance() {}
   async close() {
     this.closed = true;
     await this.writeLock;
   }
 }
+
+// packages/core/src/transport/worker.ts
+class TransportWorker {
+  queue;
+  transport;
+  config;
+  closed = false;
+  inFlightPromise = null;
+  loopPromise;
+  pendingBatch = null;
+  constructor(queue, transport, config) {
+    this.queue = queue;
+    this.transport = transport;
+    this.config = config;
+    this.loopPromise = this.start();
+  }
+  async start() {
+    while (!this.closed || this.pendingBatch || this.queue.size() > 0 || this.inFlightPromise) {
+      const batch = this.pendingBatch ?? this.queue.dequeueBatch(this.config.batchSize);
+      if (batch.length === 0) {
+        await new Promise((resolve) => setTimeout(resolve, this.config.intervalMs));
+        continue;
+      }
+      try {
+        const inFlight = this.transport.processBatch(batch);
+        this.inFlightPromise = inFlight;
+        await inFlight;
+        this.pendingBatch = null;
+      } catch (error) {
+        this.pendingBatch = batch;
+        console.error("TransportWorker.processBatch failed", error);
+        await new Promise((resolve) => setTimeout(resolve, this.config.intervalMs));
+      } finally {
+        this.inFlightPromise = null;
+      }
+    }
+  }
+  async flush(timeoutMs) {
+    const start = Date.now();
+    while ((this.queue.size() > 0 || this.pendingBatch || this.inFlightPromise) && Date.now() - start < timeoutMs) {
+      await new Promise((resolve) => setTimeout(resolve, this.config.intervalMs));
+    }
+  }
+  async close(timeoutMs = this.config.intervalMs * 50) {
+    this.closed = true;
+    const deadline = Date.now() + timeoutMs;
+    const awaitWithTimeout = async (promise, label, timeoutMs2, warnOnTimeout = true) => {
+      if (timeoutMs2 <= 0) {
+        if (warnOnTimeout) {
+          console.warn(`TransportWorker.close timed out waiting for ${label}`);
+        }
+        return false;
+      }
+      const resolvedPromise = Promise.resolve(promise);
+      let timeoutId = null;
+      const timeoutPromise = new Promise((resolve) => {
+        timeoutId = setTimeout(() => resolve(false), timeoutMs2);
+      });
+      const completed = await Promise.race([resolvedPromise.then(() => true), timeoutPromise]);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (!completed && warnOnTimeout) {
+        console.warn(`TransportWorker.close timed out waiting for ${label}`);
+      }
+      return completed;
+    };
+    const remainingTime = () => Math.max(0, deadline - Date.now());
+    const loopCompleted = await awaitWithTimeout(this.loopPromise, "loop to finish", remainingTime(), false);
+    if (!loopCompleted) {
+      console.warn("TransportWorker.close timed out waiting for loop to finish; closing transport now may cause potential data loss");
+    }
+    const safeTransportClose = async () => {
+      try {
+        await this.transport.close();
+      } catch (error) {
+        console.error("TransportWorker.close failed", error);
+      }
+    };
+    await awaitWithTimeout(safeTransportClose(), "transport to close", remainingTime());
+  }
+}
+
+// packages/core/src/create-core.ts
+function createCore(config) {
+  let transport;
+  if (config.transportType === "stdio") {
+    transport = new StdioTransport;
+  } else {
+    if (!config.httpConfig) {
+      throw new Error("HTTP transport requires httpConfig to be provided in configuration");
+    }
+    const httpConfig = HttpTransportConfigSchema.parse(config.httpConfig);
+    transport = new HttpTransport(httpConfig);
+  }
+  let partition;
+  if (config.httpConfig?.agentId) {
+    try {
+      partition = extractPartition(config.httpConfig.agentId);
+    } catch {
+      partition = undefined;
+    }
+  }
+  const queue = new InMemoryQueue;
+  const worker = new TransportWorker(queue, transport, { batchSize: 25, intervalMs: 50 });
+  const tracer = new Tracer(queue, partition);
+  const schemaName = config.httpConfig?.schemaName ?? "prefactor:agent";
+  const schemaIdentifier = config.httpConfig?.schemaIdentifier ?? "1.0.0";
+  const allowUnregisteredSchema = config.transportType === "http" && Boolean(config.httpConfig?.skipSchema || config.httpConfig?.agentSchema || config.httpConfig?.agentSchemaIdentifier);
+  const agentManager = new AgentInstanceManager(queue, {
+    schemaName,
+    schemaIdentifier,
+    allowUnregisteredSchema
+  });
+  const shutdown = async () => {
+    await worker.close();
+  };
+  return { tracer, agentManager, worker, shutdown };
+}
 export {
   truncateString,
   serializeValue,
   getLogger,
+  createCore,
   createConfig,
   configureLogging,
   Tracer,
@@ -601,10 +853,14 @@ export {
   SpanType,
   SpanStatus,
   SpanContext,
+  SchemaRegistry,
   PartialHttpConfigSchema,
+  InMemoryQueue,
   HttpTransportConfigSchema,
   HttpTransport,
-  ConfigSchema
+  DEFAULT_AGENT_SCHEMA,
+  ConfigSchema,
+  AgentInstanceManager
 };
 
-//# debugId=48E67D6DE4160D4864756E2164756E21
+//# debugId=AE4689D591D1DB9C64756E2164756E21