@prefactor/core 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,90 +1,60 @@
 // 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;
+  transport;
   options;
-  schemaRegistry = new SchemaRegistry;
-  constructor(queue, options) {
-    this.queue = queue;
+  registeredSchema = null;
+  constructor(transport, options) {
+    this.transport = transport;
     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.`);
-      }
+    if (this.registeredSchema === null) {
+      this.registeredSchema = schema;
+      this.transport.registerSchema(schema);
       return;
     }
-    const registration = {
-      schemaName: this.options.schemaName,
-      schemaIdentifier: this.options.schemaIdentifier,
-      schema
-    };
-    this.schemaRegistry.register(registration);
-    this.queue.enqueue({ type: "schema_register", data: registration });
+    const existingSchema = stableStringify(this.registeredSchema);
+    const incomingSchema = stableStringify(schema);
+    if (existingSchema !== incomingSchema) {
+      console.warn("A different schema was provided after registration; ignoring subsequent schema.");
+    }
   }
   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.`);
+    if (!this.options.allowUnregisteredSchema && this.registeredSchema === null) {
+      console.warn("Schema 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 });
+    this.transport.startAgentInstance(options);
   }
   finishInstance() {
-    this.queue.enqueue({ type: "agent_finish", data: {} });
+    this.transport.finishAgentInstance();
   }
 }
+function stableStringify(value) {
+  return JSON.stringify(normalizeValue(value));
+}
+function normalizeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeValue(entry));
+  }
+  if (value && typeof value === "object") {
+    const normalized = {};
+    const objectValue = value;
+    const keys = Object.keys(objectValue).sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+      normalized[key] = normalizeValue(objectValue[key]);
+    }
+    return normalized;
+  }
+  return value;
+}
 // packages/core/src/config.ts
 import { z } from "zod";
+var DEFAULT_RETRY_ON_STATUS_CODES = [
+  429,
+  ...Array.from({ length: 100 }, (_, index) => 500 + index)
+];
+var HttpStatusCodeSchema = z.number().int().min(100).max(599);
 var HttpTransportConfigSchema = z.object({
   apiUrl: z.string().url(),
   apiToken: z.string().min(1),
@@ -92,17 +62,13 @@ var HttpTransportConfigSchema = z.object({
   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(),
-  agentSchemaIdentifier: z.string().optional(),
-  skipSchema: z.boolean().default(false),
   requestTimeout: z.number().positive().default(30000),
-  connectTimeout: z.number().positive().default(1e4),
   maxRetries: z.number().int().nonnegative().default(3),
   initialRetryDelay: z.number().positive().default(1000),
   maxRetryDelay: z.number().positive().default(60000),
-  retryMultiplier: z.number().positive().default(2)
+  retryMultiplier: z.number().positive().default(2),
+  retryOnStatusCodes: z.array(HttpStatusCodeSchema).default([...DEFAULT_RETRY_ON_STATUS_CODES])
 });
 var PartialHttpConfigSchema = z.object({
   apiUrl: z.string().url(),
@@ -111,20 +77,16 @@ var PartialHttpConfigSchema = z.object({
   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(),
-  agentSchemaIdentifier: z.string().optional(),
-  skipSchema: z.boolean().optional(),
   requestTimeout: z.number().positive().optional(),
-  connectTimeout: z.number().positive().optional(),
   maxRetries: z.number().int().nonnegative().optional(),
   initialRetryDelay: z.number().positive().optional(),
   maxRetryDelay: z.number().positive().optional(),
-  retryMultiplier: z.number().positive().optional()
+  retryMultiplier: z.number().positive().optional(),
+  retryOnStatusCodes: z.array(HttpStatusCodeSchema).optional()
 });
 var ConfigSchema = z.object({
-  transportType: z.enum(["stdio", "http"]).default("stdio"),
+  transportType: z.enum(["http"]).default("http"),
   sampleRate: z.number().min(0).max(1).default(1),
   captureInputs: z.boolean().default(true),
   captureOutputs: z.boolean().default(true),
@@ -133,37 +95,69 @@ var ConfigSchema = z.object({
   httpConfig: PartialHttpConfigSchema.optional()
 });
 function createConfig(options) {
+  const retryOnStatusCodesFromEnv = parseRetryOnStatusCodesEnv(process.env.PREFACTOR_RETRY_ON_STATUS_CODES);
   const config = {
-    transportType: options?.transportType ?? process.env.PREFACTOR_TRANSPORT ?? "stdio",
+    transportType: options?.transportType ?? process.env.PREFACTOR_TRANSPORT ?? "http",
     sampleRate: options?.sampleRate ?? parseFloat(process.env.PREFACTOR_SAMPLE_RATE ?? "1.0"),
     captureInputs: options?.captureInputs ?? process.env.PREFACTOR_CAPTURE_INPUTS !== "false",
     captureOutputs: options?.captureOutputs ?? process.env.PREFACTOR_CAPTURE_OUTPUTS !== "false",
     maxInputLength: options?.maxInputLength ?? parseInt(process.env.PREFACTOR_MAX_INPUT_LENGTH ?? "10000", 10),
     maxOutputLength: options?.maxOutputLength ?? parseInt(process.env.PREFACTOR_MAX_OUTPUT_LENGTH ?? "10000", 10),
-    httpConfig: options?.httpConfig
+    httpConfig: options?.httpConfig ? {
+      ...options.httpConfig,
+      retryOnStatusCodes: options.httpConfig.retryOnStatusCodes ?? retryOnStatusCodesFromEnv
+    } : undefined
   };
   return ConfigSchema.parse(config);
 }
+function parseRetryOnStatusCodesEnv(value) {
+  if (!value) {
+    return;
+  }
+  const parsedCodes = value.split(",").map((status) => status.trim()).filter((status) => /^\d{3}$/.test(status)).map((status) => Number(status)).filter((status) => status >= 100 && status <= 599);
+  return parsedCodes.length > 0 ? parsedCodes : undefined;
+}
 // 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);
+// packages/core/src/tracing/active-tracer.ts
+var activeTracer;
+function setActiveTracer(tracer) {
+  activeTracer = tracer;
+}
+function getActiveTracer() {
+  return activeTracer;
+}
+function clearActiveTracer(tracer) {
+  if (!tracer || activeTracer === tracer) {
+    activeTracer = undefined;
   }
-  size() {
-    return this.items.length;
+}
+
+// packages/core/src/lifecycle.ts
+var shutdownHandlers = new Map;
+var activeCoreRuntime = null;
+function setActiveCoreRuntime(runtime) {
+  activeCoreRuntime = runtime;
+}
+function registerShutdownHandler(key, handler) {
+  shutdownHandlers.set(key, handler);
+  return () => shutdownHandlers.delete(key);
+}
+async function shutdown() {
+  for (const handler of shutdownHandlers.values()) {
+    try {
+      await handler();
+    } catch (error) {
+      console.error("Error during shutdown handler execution:", error);
+    }
   }
-  async flush() {
-    return;
+  if (activeCoreRuntime) {
+    const runtime = activeCoreRuntime;
+    activeCoreRuntime = null;
+    await runtime.shutdown();
   }
+  clearActiveTracer();
 }
 
 // packages/core/src/tracing/tracer.ts
@@ -214,38 +208,11 @@ class SpanContext {
 }
 
 // packages/core/src/tracing/span.ts
-var SpanType;
-((SpanType2) => {
-  SpanType2["AGENT"] = "agent";
-  SpanType2["LLM"] = "llm";
-  SpanType2["TOOL"] = "tool";
-  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 SpanType = {
+  AGENT: "agent",
+  LLM: "llm",
+  TOOL: "tool",
+  CHAIN: "chain"
 };
 var SpanStatus;
 ((SpanStatus2) => {
@@ -256,10 +223,10 @@ var SpanStatus;
 
 // packages/core/src/tracing/tracer.ts
 class Tracer {
-  queue;
+  transport;
   partition;
-  constructor(queue, partition) {
-    this.queue = queue;
+  constructor(transport, partition) {
+    this.transport = transport;
     this.partition = partition ?? generatePartition();
   }
   startSpan(options) {
@@ -279,14 +246,13 @@ class Tracer {
       outputs: null,
       tokenUsage: null,
       error: null,
-      metadata: options.metadata ?? {},
-      tags: options.tags ?? []
+      metadata: options.metadata ?? {}
     };
-    if (options.spanType === "agent" /* AGENT */) {
+    if (options.spanType === SpanType.AGENT) {
       try {
-        this.queue.enqueue({ type: "span_end", data: span });
+        this.transport.emit(span);
       } catch (error) {
-        console.error("Failed to enqueue agent span:", error);
+        console.error("Failed to emit agent span:", error);
       }
     }
     return span;
@@ -307,28 +273,180 @@ class Tracer {
       span.status = "success" /* SUCCESS */;
     }
     try {
-      if (span.spanType === "agent" /* AGENT */) {
-        this.queue.enqueue({ type: "span_finish", data: { spanId: span.spanId, endTime } });
+      if (span.spanType === SpanType.AGENT) {
+        this.transport.finishSpan(span.spanId, endTime);
       } else {
-        this.queue.enqueue({ type: "span_end", data: span });
+        this.transport.emit(span);
       }
     } catch (error) {
-      console.error("Failed to enqueue span action:", error);
+      console.error("Failed to emit span action:", error);
     }
   }
   async close() {
     try {
-      await this.queue.flush();
+      await this.transport.close();
+    } catch (error) {
+      console.error("Failed to close transport:", 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 flush queue:", error);
+      console.error("Failed to finish agent instance:", error);
+    }
+  }
+}
+
+// packages/core/src/queue/in-memory-queue.ts
+class InMemoryQueue {
+  items = [];
+  waiters = [];
+  isClosed = false;
+  async put(item) {
+    if (this.isClosed) {
+      throw new Error("Cannot put item into a closed queue");
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ done: false, item });
+      return;
+    }
+    this.items.push({ item });
+  }
+  async get() {
+    if (this.items.length > 0) {
+      const entry = this.items.shift();
+      if (entry) {
+        return { done: false, item: entry.item };
+      }
+    }
+    if (this.isClosed) {
+      return { done: true };
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  close() {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      if (waiter) {
+        waiter({ done: true });
+      }
+    }
+  }
+  size() {
+    return this.items.length;
+  }
+}
+
+// packages/core/src/queue/task-executor.ts
+var DEFAULT_WORKER_COUNT = 1;
+var DEFAULT_MAX_RETRIES = 0;
+var DEFAULT_RETRY_DELAY_MS = 0;
+
+class TaskExecutor {
+  queue;
+  handler;
+  isRunning = false;
+  workerPromises = [];
+  workerCount;
+  maxRetries;
+  retryDelayMs;
+  onError;
+  constructor(queue, handler, options = {}) {
+    this.queue = queue;
+    this.handler = handler;
+    this.workerCount = Math.max(options.workerCount ?? DEFAULT_WORKER_COUNT, 1);
+    this.maxRetries = Math.max(options.maxRetries ?? DEFAULT_MAX_RETRIES, 0);
+    this.retryDelayMs = Math.max(options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS, 0);
+    this.onError = options.onError;
+  }
+  start() {
+    if (this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    this.workerPromises = Array.from({ length: this.workerCount }, () => this.runWorker());
+  }
+  async stop() {
+    if (!this.isRunning) {
+      return;
+    }
+    this.isRunning = false;
+    this.queue.close();
+    await Promise.all(this.workerPromises);
+    this.workerPromises = [];
+  }
+  async runWorker() {
+    while (true) {
+      const result = await this.queue.get();
+      if (result.done) {
+        return;
+      }
+      await this.executeWithRetry(result.item);
+    }
+  }
+  async executeWithRetry(item) {
+    let attempt = 0;
+    while (attempt <= this.maxRetries) {
+      try {
+        await this.handler(item);
+        return;
+      } catch (error) {
+        if (attempt >= this.maxRetries) {
+          await this.safeOnError(error, item);
+          return;
+        }
+        if (this.retryDelayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, this.retryDelayMs));
+        }
+      }
+      attempt += 1;
+    }
+  }
+  async safeOnError(error, item) {
+    if (!this.onError) {
+      return;
+    }
+    try {
+      await this.onError(error, item);
+    } catch {
+      return;
     }
   }
 }
 
 // packages/core/src/utils/logging.ts
+var LogLevel;
+((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+})(LogLevel ||= {});
+
 class Logger {
   namespace;
-  static level = 1 /* INFO */;
+  static level = (() => {
+    const level = process.env.PREFACTOR_LOG_LEVEL?.toUpperCase();
+    if (level && level in LogLevel) {
+      return LogLevel[level];
+    }
+    return 1 /* INFO */;
+  })();
   constructor(namespace) {
     this.namespace = namespace;
   }
@@ -372,72 +490,331 @@ function configureLogging() {
   }
 }
 
+// packages/core/src/transport/http/agent-instance-client.ts
+class AgentInstanceClient {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  register(payload) {
+    return this.httpClient.request("/api/v1/agent_instance/register", {
+      method: "POST",
+      body: payload
+    });
+  }
+  async start(agentInstanceId) {
+    await this.httpClient.request(`/api/v1/agent_instance/${agentInstanceId}/start`, {
+      method: "POST",
+      body: {}
+    });
+  }
+  async finish(agentInstanceId) {
+    await this.httpClient.request(`/api/v1/agent_instance/${agentInstanceId}/finish`, {
+      method: "POST",
+      body: {}
+    });
+  }
+}
+
+// packages/core/src/transport/http/retry-policy.ts
+var JITTER_MIN = 0.5;
+function shouldRetryStatusCode(statusCode, retryOnStatusCodes) {
+  return retryOnStatusCodes.includes(statusCode);
+}
+function calculateRetryDelay(attempt, config, random = Math.random) {
+  const baseDelay = Math.min(config.initialRetryDelay * config.retryMultiplier ** attempt, config.maxRetryDelay);
+  const jitterMultiplier = JITTER_MIN + random() * JITTER_MIN;
+  return Math.round(baseDelay * jitterMultiplier);
+}
+
+// packages/core/src/transport/http/http-client.ts
+class HttpClientError extends Error {
+  url;
+  method;
+  status;
+  statusText;
+  responseBody;
+  retryable;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "HttpClientError";
+    this.url = options.url;
+    this.method = options.method;
+    this.status = options.status;
+    this.statusText = options.statusText;
+    this.responseBody = options.responseBody;
+    this.retryable = options.retryable;
+  }
+}
+
+class HttpClient {
+  config;
+  fetchFn;
+  sleep;
+  random;
+  constructor(config, dependencies = {}) {
+    this.config = config;
+    this.fetchFn = dependencies.fetchFn ?? fetch;
+    this.sleep = dependencies.sleep ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+    this.random = dependencies.random ?? Math.random;
+  }
+  async request(path, options = {}) {
+    const url = new URL(path, this.config.apiUrl).toString();
+    const method = options.method ?? "GET";
+    let attempt = 0;
+    while (true) {
+      const headers = new Headers(options.headers);
+      headers.set("Authorization", `Bearer ${this.config.apiToken}`);
+      if (options.body !== undefined && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+      }
+      const requestInit = {
+        ...options,
+        method,
+        headers,
+        body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        signal: AbortSignal.timeout(options.timeoutMs ?? this.config.requestTimeout)
+      };
+      try {
+        const response = await this.fetchFn(url, requestInit);
+        if (response.ok) {
+          return await parseResponseBody(response);
+        }
+        const responseBody = await parseResponseBody(response);
+        const canRetry = attempt < this.config.maxRetries && shouldRetryStatusCode(response.status, this.config.retryOnStatusCodes);
+        if (canRetry) {
+          const delayMs = calculateRetryDelay(attempt, this.config, this.random);
+          await this.sleep(delayMs);
+          attempt += 1;
+          continue;
+        }
+        throw new HttpClientError(`HTTP request failed with status ${response.status}`, {
+          url,
+          method,
+          status: response.status,
+          statusText: response.statusText,
+          responseBody,
+          retryable: shouldRetryStatusCode(response.status, this.config.retryOnStatusCodes)
+        });
+      } catch (error) {
+        if (error instanceof HttpClientError) {
+          throw error;
+        }
+        const canRetry = attempt < this.config.maxRetries && isRetryableNetworkError(error);
+        if (canRetry) {
+          const delayMs = calculateRetryDelay(attempt, this.config, this.random);
+          await this.sleep(delayMs);
+          attempt += 1;
+          continue;
+        }
+        throw new HttpClientError("HTTP request failed due to network error", {
+          url,
+          method,
+          retryable: false,
+          cause: error
+        });
+      }
+    }
+  }
+}
+function isRetryableNetworkError(error) {
+  if (error instanceof TypeError) {
+    return true;
+  }
+  if (error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    return true;
+  }
+  if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    return true;
+  }
+  return false;
+}
+async function parseResponseBody(response) {
+  const bodyText = await response.text();
+  if (!bodyText) {
+    return null;
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      return bodyText;
+    }
+  }
+  try {
+    return JSON.parse(bodyText);
+  } catch {
+    return bodyText;
+  }
+}
+
+// packages/core/src/transport/http/agent-span-client.ts
+class AgentSpanClient {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  create(payload) {
+    return this.httpClient.request("/api/v1/agent_spans", {
+      method: "POST",
+      body: payload
+    });
+  }
+  async finish(spanId, timestamp) {
+    try {
+      await this.httpClient.request(`/api/v1/agent_spans/${spanId}/finish`, {
+        method: "POST",
+        body: { timestamp }
+      });
+    } catch (error) {
+      if (error instanceof HttpClientError && error.status === 409 && isAlreadyFinishedError(error.responseBody)) {
+        return;
+      }
+      throw error;
+    }
+  }
+}
+function isAlreadyFinishedError(responseBody) {
+  if (!responseBody || typeof responseBody !== "object") {
+    return false;
+  }
+  const payload = responseBody;
+  return payload.code === "invalid_action";
+}
+
 // packages/core/src/transport/http.ts
 var logger = getLogger("http-transport");
 
 class HttpTransport {
   config;
   closed = false;
+  actionQueue = new InMemoryQueue;
+  taskExecutor;
+  agentInstanceClient;
+  agentSpanClient;
+  previousAgentSchema = null;
+  requiresNewAgentIdentifier = false;
+  previousAgentIdentifier = null;
   agentInstanceId = null;
   spanIdMap = new Map;
   pendingFinishes = new Map;
+  pendingChildren = new Map;
   constructor(config) {
     this.config = config;
+    const httpClient = new HttpClient(config);
+    this.agentInstanceClient = new AgentInstanceClient(httpClient);
+    this.agentSpanClient = new AgentSpanClient(httpClient);
+    this.taskExecutor = new TaskExecutor(this.actionQueue, this.processAction, {
+      workerCount: 1,
+      onError: async (error) => {
+        logger.error("Error processing HTTP action:", error);
+      }
+    });
+    this.taskExecutor.start();
+  }
+  registerSchema(schema) {
+    this.enqueue({ type: "schema_register", schema });
+  }
+  startAgentInstance(options) {
+    this.enqueue({ type: "agent_start", options });
+  }
+  finishAgentInstance() {
+    this.enqueue({ type: "agent_finish" });
+  }
+  emit(span) {
+    this.enqueue({ type: "span_end", span });
+  }
+  finishSpan(spanId, endTime) {
+    this.enqueue({ type: "span_finish", spanId, endTime });
+  }
+  async close() {
+    this.closed = true;
+    await this.taskExecutor.stop();
+    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();
+    }
+    if (this.pendingChildren.size > 0) {
+      logger.warn(`Transport closed with ${this.pendingChildren.size} unresolved parent span reference(s)`);
+      this.pendingChildren.clear();
+    }
   }
-  async processBatch(items) {
-    if (this.closed || items.length === 0) {
+  enqueue(action) {
+    if (this.closed) {
       return;
     }
-    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;
+    this.actionQueue.put(action).catch((error) => {
+      logger.error("Failed to enqueue HTTP action:", error);
+    });
+  }
+  processAction = async (action) => {
+    switch (action.type) {
+      case "schema_register": {
+        const incomingSchema = JSON.stringify(action.schema);
+        if (this.previousAgentSchema !== null && this.previousAgentSchema !== incomingSchema) {
+          this.requiresNewAgentIdentifier = true;
+          this.previousAgentIdentifier = this.config.agentIdentifier;
+          this.agentInstanceId = null;
+        }
+        this.previousAgentSchema = incomingSchema;
+        this.config.agentSchema = action.schema;
+        return;
       }
-    }
-    for (const item of items) {
-      try {
-        switch (item.type) {
-          case "schema_register":
-            break;
-          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 "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;
+      case "agent_start": {
+        if (this.requiresNewAgentIdentifier) {
+          const nextAgentIdentifier = action.options?.agentIdentifier;
+          if (nextAgentIdentifier === undefined || nextAgentIdentifier === this.previousAgentIdentifier) {
+            logger.error("Schema changed; starting an agent requires a new agentIdentifier value.");
+            return;
           }
+          this.requiresNewAgentIdentifier = false;
+          this.previousAgentIdentifier = null;
         }
-      } catch (error) {
-        logger.error("Error processing batch item:", error);
+        if (action.options?.agentId !== undefined)
+          this.config.agentId = action.options.agentId;
+        if (action.options?.agentIdentifier !== undefined) {
+          this.config.agentIdentifier = action.options.agentIdentifier;
+        }
+        if (action.options?.agentName !== undefined)
+          this.config.agentName = action.options.agentName;
+        if (action.options?.agentDescription !== undefined) {
+          this.config.agentDescription = action.options.agentDescription;
+        }
+        await this.startAgentInstanceHttp();
+        return;
+      }
+      case "agent_finish":
+        await this.finishAgentInstanceHttp();
+        return;
+      case "span_end":
+        if (!this.agentInstanceId) {
+          await this.ensureAgentRegistered();
+        }
+        if (action.span.parentSpanId && !this.spanIdMap.has(action.span.parentSpanId)) {
+          this.queuePendingChild(action.span.parentSpanId, action.span);
+          return;
+        }
+        await this.sendSpan(action.span);
+        return;
+      case "span_finish": {
+        const backendSpanId = this.spanIdMap.get(action.spanId);
+        if (backendSpanId) {
+          const timestamp = new Date(action.endTime).toISOString();
+          await this.finishSpanHttp({ spanId: action.spanId, timestamp });
+        } else {
+          this.pendingFinishes.set(action.spanId, action.endTime);
+        }
+        return;
       }
     }
-  }
+  };
   async processPendingFinishes(spanId) {
+    if (!this.pendingFinishes.has(spanId)) {
+      return;
+    }
     const pendingEndTime = this.pendingFinishes.get(spanId);
-    if (!pendingEndTime) {
+    if (pendingEndTime === undefined) {
       return;
     }
     try {
@@ -448,56 +825,48 @@ class HttpTransport {
       logger.error("Error processing pending span finish:", error);
     }
   }
-  async sendSpan(span, retry = 0) {
-    const url = `${this.config.apiUrl}/api/v1/agent_spans`;
+  async sendSpan(span) {
     const payload = this.transformSpanToApiFormat(span);
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiToken}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(payload),
-        signal: AbortSignal.timeout(this.config.requestTimeout)
-      });
-      if (response.ok) {
-        const data = await response.json();
-        const backendSpanId = data?.details?.id;
-        if (backendSpanId) {
-          this.spanIdMap.set(span.spanId, backendSpanId);
-          await this.processPendingFinishes(span.spanId);
-        }
+      const response = await this.agentSpanClient.create(payload);
+      const backendSpanId = response.details?.id;
+      if (!backendSpanId) {
         return;
       }
-      if ((response.status >= 500 || response.status === 429) && retry < this.config.maxRetries) {
-        const delay = Math.min(this.config.initialRetryDelay * this.config.retryMultiplier ** retry, this.config.maxRetryDelay);
-        logger.debug(`Retrying span send after ${delay}ms (attempt ${retry + 1})`);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        return this.sendSpan(span, retry + 1);
-      }
-      logger.error(`Failed to send span: ${response.status} ${response.statusText}`);
+      this.spanIdMap.set(span.spanId, backendSpanId);
+      await this.processPendingFinishes(span.spanId);
+      await this.processPendingChildren(span.spanId);
     } catch (error) {
       logger.error("Error sending span:", error);
-      if (retry < this.config.maxRetries) {
-        const delay = Math.min(this.config.initialRetryDelay * this.config.retryMultiplier ** retry, this.config.maxRetryDelay);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        return this.sendSpan(span, retry + 1);
-      }
+    }
+  }
+  queuePendingChild(parentSpanId, childSpan) {
+    const existingChildren = this.pendingChildren.get(parentSpanId) ?? [];
+    existingChildren.push(childSpan);
+    this.pendingChildren.set(parentSpanId, existingChildren);
+  }
+  async processPendingChildren(parentSpanId) {
+    const waitingChildren = this.pendingChildren.get(parentSpanId);
+    if (!waitingChildren || waitingChildren.length === 0) {
+      return;
+    }
+    this.pendingChildren.delete(parentSpanId);
+    for (const childSpan of waitingChildren) {
+      await this.sendSpan(childSpan);
     }
   }
   transformSpanToApiFormat(span) {
     const startedAt = new Date(span.startTime).toISOString();
     const finishedAt = span.endTime ? new Date(span.endTime).toISOString() : null;
+    const apiStatus = this.mapStatusForApi(span.status);
     const payload = {
       span_id: span.spanId,
       trace_id: span.traceId,
       name: span.name,
-      status: span.status,
+      status: apiStatus,
       inputs: span.inputs,
       outputs: span.outputs,
       metadata: span.metadata,
-      tags: span.tags,
       token_usage: null,
       error: null
     };
@@ -520,6 +889,7 @@ class HttpTransport {
       details: {
         agent_instance_id: this.agentInstanceId,
         schema_name: span.spanType,
+        status: apiStatus,
         payload,
         parent_span_id: parentSpanId,
         started_at: startedAt,
@@ -527,14 +897,22 @@ class HttpTransport {
       }
     };
   }
-  getDefaultSchema() {
-    return DEFAULT_AGENT_SCHEMA;
+  mapStatusForApi(status) {
+    switch (status) {
+      case "running":
+        return "active";
+      case "success":
+        return "complete";
+      case "error":
+        return "failed";
+      default:
+        return "active";
+    }
   }
   async ensureAgentRegistered() {
     if (this.agentInstanceId) {
-      return;
+      return true;
     }
-    const url = `${this.config.apiUrl}/api/v1/agent_instance/register`;
     const payload = {};
     if (this.config.agentId)
       payload.agent_id = this.config.agentId;
@@ -545,61 +923,25 @@ class HttpTransport {
         description: this.config.agentDescription || ""
       };
     }
-    if (this.config.skipSchema) {
-      logger.debug("Skipping schema in registration (skipSchema=true)");
-    } else if (this.config.agentSchema) {
-      logger.debug("Using custom agent schema");
+    if (this.config.agentSchema) {
       payload.agent_schema_version = this.config.agentSchema;
-    } else if (this.config.agentSchemaIdentifier) {
-      logger.debug(`Using schema version: ${this.config.agentSchemaIdentifier}`);
-      payload.agent_schema_version = {
-        external_identifier: this.config.agentSchemaIdentifier
-      };
-    } else {
-      logger.debug("Using default hardcoded schema (v1.0.0)");
-      payload.agent_schema_version = this.getDefaultSchema();
     }
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiToken}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(payload),
-        signal: AbortSignal.timeout(this.config.requestTimeout)
-      });
-      if (response.ok) {
-        const data = await response.json();
-        this.agentInstanceId = data?.details?.id ?? null;
-        logger.debug(`Registered agent instance: ${this.agentInstanceId}`);
-      } else {
-        logger.error(`Failed to register agent: ${response.status} ${response.statusText}`);
-      }
+      const data = await this.agentInstanceClient.register(payload);
+      this.agentInstanceId = data.details?.id ?? null;
     } catch (error) {
       logger.error("Error registering agent:", error);
     }
+    return this.agentInstanceId !== null;
   }
   async startAgentInstanceHttp() {
-    await this.ensureAgentRegistered();
-    if (!this.agentInstanceId) {
+    const isRegistered = await this.ensureAgentRegistered();
+    if (!isRegistered || !this.agentInstanceId) {
       logger.error("Cannot start agent instance: not registered");
       return;
     }
-    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/start`;
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiToken}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({}),
-        signal: AbortSignal.timeout(this.config.requestTimeout)
-      });
-      if (!response.ok) {
-        logger.error(`Failed to start agent instance: ${response.status} ${response.statusText}`);
-      }
+      await this.agentInstanceClient.start(this.agentInstanceId);
     } catch (error) {
       logger.error("Error starting agent instance:", error);
     }
@@ -609,20 +951,8 @@ class HttpTransport {
       logger.error("Cannot finish agent instance: not registered");
       return;
     }
-    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/finish`;
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiToken}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({}),
-        signal: AbortSignal.timeout(this.config.requestTimeout)
-      });
-      if (!response.ok) {
-        logger.error(`Failed to finish agent instance: ${response.status} ${response.statusText}`);
-      }
+      await this.agentInstanceClient.finish(this.agentInstanceId);
     } catch (error) {
       logger.error("Error finishing agent instance:", error);
     }
@@ -634,33 +964,76 @@ class HttpTransport {
       logger.warn(`Cannot finish span ${data.spanId}: backend ID not found`);
       return;
     }
-    const url = `${this.config.apiUrl}/api/v1/agent_spans/${backendSpanId}/finish`;
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiToken}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ timestamp: data.timestamp }),
-        signal: AbortSignal.timeout(this.config.requestTimeout)
-      });
-      if (!response.ok) {
-        logger.error(`Failed to finish span: ${response.status} ${response.statusText}`);
-      }
+      await this.agentSpanClient.finish(backendSpanId, data.timestamp);
     } catch (error) {
       logger.error("Error finishing span:", error);
     }
   }
-  async close() {
-    this.closed = true;
-    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/create-core.ts
+function createCore(config) {
+  if (!config.httpConfig) {
+    throw new Error("HTTP transport requires httpConfig to be provided in configuration");
+  }
+  const httpConfig = HttpTransportConfigSchema.parse(config.httpConfig);
+  const transport = new HttpTransport(httpConfig);
+  let partition;
+  if (config.httpConfig.agentId) {
+    try {
+      partition = extractPartition(config.httpConfig.agentId);
+    } catch {
+      partition = undefined;
     }
   }
+  const tracer = new Tracer(transport, partition);
+  setActiveTracer(tracer);
+  const allowUnregisteredSchema = Boolean(config.httpConfig.agentSchema);
+  const agentManager = new AgentInstanceManager(transport, {
+    allowUnregisteredSchema
+  });
+  const shutdown2 = async () => {
+    await tracer.close();
+    clearActiveTracer(tracer);
+    setActiveCoreRuntime(null);
+  };
+  const runtime = { tracer, agentManager, shutdown: shutdown2 };
+  setActiveCoreRuntime(runtime);
+  return runtime;
+}
+// packages/core/src/tracing/with-span.ts
+async function withSpan(tracerOrOptions, optionsOrFn, maybeFn) {
+  const { tracer, options, fn } = resolveArgs(tracerOrOptions, optionsOrFn, maybeFn);
+  const span = tracer.startSpan(options);
+  try {
+    const result = await SpanContext.runAsync(span, async () => await fn());
+    tracer.endSpan(span);
+    return result;
+  } catch (error) {
+    const normalizedError = error instanceof Error ? error : new Error(String(error));
+    tracer.endSpan(span, { error: normalizedError });
+    throw error;
+  }
+}
+function resolveArgs(tracerOrOptions, optionsOrFn, maybeFn) {
+  if (maybeFn) {
+    return {
+      tracer: tracerOrOptions,
+      options: optionsOrFn,
+      fn: maybeFn
+    };
+  }
+  const tracer = getActiveTracer();
+  if (!tracer) {
+    throw new Error("No active tracer found. Initialize Prefactor first or pass a tracer explicitly.");
+  }
+  return {
+    tracer,
+    options: tracerOrOptions,
+    fn: optionsOrFn
+  };
 }
-
 // packages/core/src/utils/serialization.ts
 function truncateString(value, maxLength) {
   if (value.length <= maxLength) {
@@ -694,173 +1067,25 @@ function serializeValue(value, maxLength = 1e4) {
     return `<${typeof value} object>`;
   }
 }
-
-// packages/core/src/transport/stdio.ts
-class StdioTransport {
-  closed = false;
-  writeLock = Promise.resolve();
-  async processBatch(items) {
-    if (this.closed || items.length === 0) {
-      return;
-    }
-    this.writeLock = this.writeLock.then(async () => {
-      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 queue action to stdout:", error);
-        }
-      }
-    });
-    await this.writeLock;
-  }
-  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 {
+  withSpan,
   truncateString,
+  shutdown,
   serializeValue,
+  registerShutdownHandler,
   getLogger,
   createCore,
   createConfig,
   configureLogging,
   Tracer,
-  StdioTransport,
   SpanType,
   SpanStatus,
   SpanContext,
-  SchemaRegistry,
   PartialHttpConfigSchema,
-  InMemoryQueue,
   HttpTransportConfigSchema,
   HttpTransport,
-  DEFAULT_AGENT_SCHEMA,
   ConfigSchema,
   AgentInstanceManager
 };
 
-//# debugId=AE4689D591D1DB9C64756E2164756E21
+//# debugId=9E6C81B271F2076D64756E2164756E21