@stackbone/sdk 0.1.0-alpha.1 → 0.1.0-alpha.3

package/observability/index.js

@@ -0,0 +1,587 @@
+import { appendFile, mkdir } from 'fs/promises';
+import { homedir } from 'os';
+import { resolve, dirname } from 'path';
+import { randomUUID } from 'crypto';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// package.json
+var version = "0.1.0-alpha.2";
+
+// src/observability/logger.ts
+var LOG_LEVELS = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60
+};
+var DEFAULT_BATCH_SIZE = 50;
+var DEFAULT_INTERVAL_MS = 1e3;
+var DEFAULT_HTTP_TIMEOUT_MS = 5e3;
+function createPlatformLogger(options) {
+  const otelEndpoint = options.otelEndpoint ?? void 0;
+  const mode = options.mode ?? (otelEndpoint ? "cloud" : "local");
+  const baseBindings = {
+    run_id: options.runId
+  };
+  if (options.installationId !== void 0) baseBindings["installation_id"] = options.installationId;
+  if (options.agentId !== void 0) baseBindings["agent_id"] = options.agentId;
+  const destination = mode === "cloud" ? new OtlpHttpDestination({
+    endpoint: otelEndpoint ?? "",
+    resourceAttributes: options.resourceAttributes ?? {},
+    httpTimeoutMs: options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+    flushBatchSize: options.flushBatchSize ?? DEFAULT_BATCH_SIZE,
+    flushIntervalMs: options.flushIntervalMs ?? DEFAULT_INTERVAL_MS,
+    ...options.fetchImpl !== void 0 ? {
+      fetchImpl: options.fetchImpl
+    } : {}
+  }) : new JsonlFileDestination({
+    runId: options.runId,
+    runsDir: options.runsDir ?? defaultRunsDir(),
+    ...options.appendFileImpl !== void 0 ? {
+      appendFileImpl: options.appendFileImpl
+    } : {},
+    ...options.mkdirImpl !== void 0 ? {
+      mkdirImpl: options.mkdirImpl
+    } : {}
+  });
+  const now = options.now ?? Date.now;
+  return buildLogger({
+    destination,
+    baseBindings,
+    mode,
+    now
+  });
+}
+__name(createPlatformLogger, "createPlatformLogger");
+function buildLogger(opts) {
+  const writeAt = /* @__PURE__ */ __name((level, msgOrObj, msg) => {
+    const time = opts.now();
+    const levelNumber = LOG_LEVELS[level];
+    const record = {
+      level: levelNumber,
+      time,
+      msg: "",
+      run_id: String(opts.baseBindings["run_id"] ?? ""),
+      ...opts.baseBindings
+    };
+    if (typeof msgOrObj === "string") {
+      record.msg = msgOrObj;
+    } else if (msgOrObj && typeof msgOrObj === "object") {
+      Object.assign(record, msgOrObj);
+      if (typeof msg === "string") record.msg = msg;
+      else if (typeof record.msg !== "string") record.msg = "";
+    }
+    opts.destination.write(record);
+  }, "writeAt");
+  const child = /* @__PURE__ */ __name((bindings) => buildLogger({
+    ...opts,
+    baseBindings: {
+      ...opts.baseBindings,
+      ...bindings
+    }
+  }), "child");
+  return {
+    mode: opts.mode,
+    trace: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("trace", msgOrObj, msg), "trace"),
+    debug: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("debug", msgOrObj, msg), "debug"),
+    info: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("info", msgOrObj, msg), "info"),
+    warn: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("warn", msgOrObj, msg), "warn"),
+    error: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("error", msgOrObj, msg), "error"),
+    fatal: /* @__PURE__ */ __name((msgOrObj, msg) => writeAt("fatal", msgOrObj, msg), "fatal"),
+    child,
+    flush: /* @__PURE__ */ __name(() => opts.destination.flush(), "flush"),
+    close: /* @__PURE__ */ __name(() => opts.destination.close(), "close")
+  };
+}
+__name(buildLogger, "buildLogger");
+var JsonlFileDestination = class JsonlFileDestination2 {
+  static {
+    __name(this, "JsonlFileDestination");
+  }
+  path;
+  appendFile;
+  mkdir;
+  inFlight = Promise.resolve();
+  dirReady = false;
+  constructor(opts) {
+    this.path = resolve(opts.runsDir, `${opts.runId}.jsonl`);
+    this.appendFile = opts.appendFileImpl ?? ((p, d) => appendFile(p, d, "utf8"));
+    this.mkdir = opts.mkdirImpl ?? (async (p) => {
+      await mkdir(p, {
+        recursive: true
+      });
+    });
+  }
+  write(record) {
+    const line = `${JSON.stringify(record)}
+`;
+    this.inFlight = this.inFlight.then(async () => {
+      if (!this.dirReady) {
+        await this.mkdir(dirname(this.path));
+        this.dirReady = true;
+      }
+      try {
+        await this.appendFile(this.path, line);
+      } catch (error) {
+        process.stderr.write(`[stackbone/sdk] PlatformLogger JSONL write failed: ${error instanceof Error ? error.message : String(error)}
+`);
+      }
+    });
+  }
+  async flush() {
+    await this.inFlight;
+  }
+  async close() {
+    await this.flush();
+  }
+};
+var OtlpHttpDestination = class OtlpHttpDestination2 {
+  static {
+    __name(this, "OtlpHttpDestination");
+  }
+  url;
+  resourceAttributes;
+  httpTimeoutMs;
+  flushBatchSize;
+  flushIntervalMs;
+  fetchImpl;
+  buffer = [];
+  timer = null;
+  inFlight = Promise.resolve();
+  closed = false;
+  constructor(opts) {
+    this.url = `${opts.endpoint.replace(/\/+$/, "")}/v1/logs`;
+    this.resourceAttributes = opts.resourceAttributes;
+    this.httpTimeoutMs = opts.httpTimeoutMs;
+    this.flushBatchSize = opts.flushBatchSize;
+    this.flushIntervalMs = opts.flushIntervalMs;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+  write(record) {
+    if (this.closed) return;
+    this.buffer.push(record);
+    if (this.buffer.length >= this.flushBatchSize) {
+      void this.flush();
+    } else {
+      this.armTimer();
+    }
+  }
+  async flush() {
+    await this.inFlight;
+    if (this.buffer.length === 0) return;
+    const drained = this.buffer.splice(0, this.buffer.length);
+    this.disarmTimer();
+    this.inFlight = this.post(drained).catch((error) => {
+      process.stderr.write(`[stackbone/sdk] PlatformLogger OTLP POST failed: ${error instanceof Error ? error.message : String(error)}
+`);
+    });
+    await this.inFlight;
+  }
+  async close() {
+    this.closed = true;
+    await this.flush();
+  }
+  armTimer() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  disarmTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  async post(records) {
+    const body = JSON.stringify(buildOtlpLogsBody(records, this.resourceAttributes));
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.httpTimeoutMs);
+    try {
+      const resp = await this.fetchImpl(this.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json"
+        },
+        body,
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        throw new Error(`HTTP ${resp.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+var SDK_SCOPE = {
+  name: "@stackbone/sdk",
+  version
+};
+function buildOtlpLogsBody(records, resourceAttributes) {
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: toOtlpAttributes(resourceAttributes)
+        },
+        scopeLogs: [
+          {
+            scope: SDK_SCOPE,
+            logRecords: records.map(toOtlpLogRecord)
+          }
+        ]
+      }
+    ]
+  };
+}
+__name(buildOtlpLogsBody, "buildOtlpLogsBody");
+function toOtlpLogRecord(record) {
+  const { level, time, msg, ...rest } = record;
+  return {
+    timeUnixNano: `${time * 1e6}`,
+    severityNumber: level,
+    severityText: severityText(level),
+    body: {
+      stringValue: msg
+    },
+    attributes: toOtlpAttributesFromUnknown(rest)
+  };
+}
+__name(toOtlpLogRecord, "toOtlpLogRecord");
+var SEVERITY_TEXT_BY_LEVEL = Object.fromEntries(Object.entries(LOG_LEVELS).map(([name, value]) => [
+  value,
+  name.toUpperCase()
+]));
+function severityText(level) {
+  return SEVERITY_TEXT_BY_LEVEL[level] ?? "INFO";
+}
+__name(severityText, "severityText");
+function toOtlpAttributes(attrs) {
+  return Object.entries(attrs).map(([key, value]) => ({
+    key,
+    value: {
+      stringValue: value
+    }
+  }));
+}
+__name(toOtlpAttributes, "toOtlpAttributes");
+function toOtlpAttributesFromUnknown(attrs) {
+  const out = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value === null || value === void 0) continue;
+    if (typeof value === "string") {
+      out.push({
+        key,
+        value: {
+          stringValue: value
+        }
+      });
+    } else if (typeof value === "number") {
+      if (Number.isInteger(value)) out.push({
+        key,
+        value: {
+          intValue: String(value)
+        }
+      });
+      else out.push({
+        key,
+        value: {
+          doubleValue: value
+        }
+      });
+    } else if (typeof value === "boolean") {
+      out.push({
+        key,
+        value: {
+          boolValue: value
+        }
+      });
+    } else {
+      out.push({
+        key,
+        value: {
+          stringValue: JSON.stringify(value)
+        }
+      });
+    }
+  }
+  return out;
+}
+__name(toOtlpAttributesFromUnknown, "toOtlpAttributesFromUnknown");
+function defaultRunsDir() {
+  return resolve(homedir(), ".stackbone", "dev", "runs");
+}
+__name(defaultRunsDir, "defaultRunsDir");
+var RUN_STEP_TYPES = [
+  "agent",
+  "llm_call",
+  "db_query",
+  "http_fetch",
+  "queue_publish",
+  "hitl_pause",
+  "tool_call",
+  "rag_query",
+  "storage_op"
+];
+var STEP_TYPE_ATTRIBUTE = "stackbone.step.type";
+var RUN_ID_ATTRIBUTE = "stackbone.run.id";
+var NAME_PREFIX_MAP = [
+  [
+    /^stackbone\.ai\./,
+    "llm_call"
+  ],
+  [
+    /^stackbone\.db\./,
+    "db_query"
+  ],
+  [
+    /^stackbone\.http\./,
+    "http_fetch"
+  ],
+  [
+    /^stackbone\.queues\./,
+    "queue_publish"
+  ],
+  [
+    /^stackbone\.approval\./,
+    "hitl_pause"
+  ],
+  [
+    /^stackbone\.tool\./,
+    "tool_call"
+  ],
+  [
+    /^stackbone\.rag\./,
+    "rag_query"
+  ],
+  [
+    /^stackbone\.storage\./,
+    "storage_op"
+  ]
+];
+var DEFAULT_BATCH_SIZE2 = 50;
+var DEFAULT_INTERVAL_MS2 = 500;
+var RunStepsSpanProcessor = class {
+  static {
+    __name(this, "RunStepsSpanProcessor");
+  }
+  buffer = [];
+  stepIdBySpanId = /* @__PURE__ */ new Map();
+  batchSize;
+  intervalMs;
+  resolveStepType;
+  newId;
+  connectionString;
+  ownsSql;
+  sql;
+  timer = null;
+  inFlight = null;
+  constructor(options = {}) {
+    this.batchSize = options.flushBatchSize ?? DEFAULT_BATCH_SIZE2;
+    this.intervalMs = options.flushIntervalMs ?? DEFAULT_INTERVAL_MS2;
+    this.resolveStepType = options.resolveStepType ?? defaultStepTypeResolver;
+    this.newId = options.newId ?? randomUUID;
+    this.connectionString = options.connectionString;
+    if (options.sql) {
+      this.sql = options.sql;
+      this.ownsSql = false;
+    } else {
+      this.sql = null;
+      this.ownsSql = true;
+    }
+  }
+  // OTel calls onStart for the parent before any child, and onEnd for
+  // children before the parent. Reserving the UUID up-front lets the child's
+  // onEnd resolve `parent_step_id` synchronously — the alternative (looking
+  // up the parent at write time) would race the buffer flush.
+  onStart(span) {
+    const spanId = span.spanContext().spanId;
+    if (!this.stepIdBySpanId.has(spanId)) {
+      this.stepIdBySpanId.set(spanId, this.newId());
+    }
+  }
+  onEnd(span) {
+    const row = this.buildRow(span);
+    if (!row) return;
+    this.buffer.push(row);
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    } else {
+      this.armTimer();
+    }
+  }
+  async forceFlush() {
+    await this.flush();
+  }
+  async shutdown() {
+    this.disarmTimer();
+    await this.flush();
+    if (this.ownsSql && this.sql?.end) {
+      await this.sql.end().catch(() => void 0);
+    }
+  }
+  buildRow(span) {
+    const spanId = span.spanContext().spanId;
+    const stepId = this.stepIdBySpanId.get(spanId) ?? this.newId();
+    this.stepIdBySpanId.delete(spanId);
+    const runId = readString(span.attributes[RUN_ID_ATTRIBUTE]);
+    if (!runId) return null;
+    const parentSpanId = span.parentSpanContext?.spanId ?? span.parentSpanId ?? null;
+    const parentStepId = parentSpanId ? this.stepIdBySpanId.get(parentSpanId) ?? null : null;
+    const startedAt = formatHrTime(span.startTime);
+    const finishedAt = formatHrTime(span.endTime ?? span.startTime);
+    const durationMs = hrTimeToMs(span.duration ?? diffHrTime(span.endTime, span.startTime));
+    const isError = span.status?.code === 2;
+    return {
+      id: stepId,
+      run_id: runId,
+      parent_step_id: parentStepId,
+      type: this.resolveStepType(span),
+      name: span.name,
+      status: isError ? "error" : "ok",
+      payload: serialisablePayload(span.attributes),
+      error: isError ? {
+        message: span.status?.message ?? "span ended with ERROR status"
+      } : null,
+      started_at: startedAt,
+      finished_at: finishedAt,
+      duration_ms: durationMs
+    };
+  }
+  armTimer() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.intervalMs);
+    this.timer.unref?.();
+  }
+  disarmTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  async flush() {
+    if (this.inFlight) {
+      await this.inFlight;
+    }
+    if (this.buffer.length === 0) return;
+    const drained = this.buffer.splice(0, this.buffer.length);
+    this.disarmTimer();
+    this.inFlight = this.writeBatch(drained).finally(() => {
+      this.inFlight = null;
+    });
+    await this.inFlight;
+  }
+  async ensureSql() {
+    if (this.sql) return this.sql;
+    if (!this.connectionString) return null;
+    const mod = await import('postgres');
+    this.sql = mod.default(this.connectionString);
+    return this.sql;
+  }
+  async writeBatch(rows) {
+    try {
+      const sql = await this.ensureSql();
+      if (!sql) {
+        process.stderr.write("[stackbone/sdk] RunStepsSpanProcessor dropped batch: no DATABASE_URL configured.\n");
+        return;
+      }
+      const placeholders = [];
+      const params = [];
+      for (const row of rows) {
+        const base = params.length;
+        placeholders.push(`($${base + 1}::uuid, $${base + 2}::uuid, $${base + 3}::uuid, $${base + 4}, $${base + 5}, $${base + 6}, $${base + 7}::jsonb, $${base + 8}::jsonb, $${base + 9}::timestamptz, $${base + 10}::timestamptz, $${base + 11}::int)`);
+        params.push(row.id, row.run_id, row.parent_step_id, row.type, row.name, row.status, JSON.stringify(row.payload), row.error ? JSON.stringify(row.error) : null, row.started_at, row.finished_at, row.duration_ms);
+      }
+      const text = `INSERT INTO stackbone_platform.run_steps (
+          id, run_id, parent_step_id, type, name, status, payload, error,
+          started_at, finished_at, duration_ms
+        ) VALUES ${placeholders.join(", ")}`;
+      await sql.unsafe(text, params);
+    } catch (error) {
+      process.stderr.write(`[stackbone/sdk] RunStepsSpanProcessor write failed: ${error instanceof Error ? error.message : String(error)}
+`);
+    }
+  }
+};
+var defaultStepTypeResolver = /* @__PURE__ */ __name((span) => {
+  const explicit = readString(span.attributes[STEP_TYPE_ATTRIBUTE]);
+  if (explicit && RUN_STEP_TYPES.includes(explicit)) {
+    return explicit;
+  }
+  for (const [pattern, type] of NAME_PREFIX_MAP) {
+    if (pattern.test(span.name)) return type;
+  }
+  return "agent";
+}, "defaultStepTypeResolver");
+var readString = /* @__PURE__ */ __name((value) => typeof value === "string" && value.length > 0 ? value : void 0, "readString");
+var formatHrTime = /* @__PURE__ */ __name((hr) => new Date(hr ? hrTimeToMs(hr) : Date.now()).toISOString(), "formatHrTime");
+var hrTimeToMs = /* @__PURE__ */ __name((hr) => {
+  if (!hr) return 0;
+  const [seconds, nanos] = hr;
+  return seconds * 1e3 + Math.floor(nanos / 1e6);
+}, "hrTimeToMs");
+var diffHrTime = /* @__PURE__ */ __name((end, start) => {
+  if (!end || !start) return void 0;
+  const seconds = end[0] - start[0];
+  const nanos = end[1] - start[1];
+  return [
+    seconds,
+    nanos
+  ];
+}, "diffHrTime");
+var serialisablePayload = /* @__PURE__ */ __name((attributes) => {
+  const out = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (key === RUN_ID_ATTRIBUTE) continue;
+    if (key === STEP_TYPE_ATTRIBUTE) continue;
+    out[key] = value;
+  }
+  return out;
+}, "serialisablePayload");
+
+// src/observability/aggregate-run-cost.ts
+var SQL = `WITH llm_costs AS (
+    SELECT COALESCE(SUM((payload->>'cost_usd')::numeric), 0) AS total
+      FROM stackbone_platform.run_steps
+     WHERE run_id = $1::uuid
+       AND type = 'llm_call'
+  )
+  UPDATE stackbone_platform.runs
+     SET cost_estimated_usd = (SELECT total FROM llm_costs)
+   WHERE id = $1::uuid
+  RETURNING cost_estimated_usd`;
+async function aggregateRunCost(runId, options) {
+  const result = await options.sql.unsafe(SQL, [
+    runId
+  ]);
+  const row = result[0];
+  if (!row) {
+    return {
+      costEstimatedUsd: 0
+    };
+  }
+  const raw = row.cost_estimated_usd;
+  if (raw === null || raw === void 0) return {
+    costEstimatedUsd: 0
+  };
+  const num = typeof raw === "string" ? Number(raw) : raw;
+  return {
+    costEstimatedUsd: Number.isFinite(num) ? num : 0
+  };
+}
+__name(aggregateRunCost, "aggregateRunCost");
+
+export { LOG_LEVELS, RUN_ID_ATTRIBUTE, RUN_STEP_TYPES, RunStepsSpanProcessor, STEP_TYPE_ATTRIBUTE, aggregateRunCost, createPlatformLogger, defaultRunsDir };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map