@lostgradient/weft 0.2.0

package/dist/mcp/tools.js

@@ -0,0 +1,262 @@
+import { RegistrySchemaConversionError } from "../core/registry-snapshot.js";
+import { runtimeWorkflowEngine } from "../core/runtime-workflow-engine.js";
+import { definitionSchemaToJsonSchema } from "../core/types/definition-schema-to-json.js";
+import {
+  McpToolExecutionError,
+  assertScope,
+  getVisibleWorkflowState,
+  listVisibleWorkflows
+} from "./access.js";
+import { parseMcpListFilter } from "./list-filter.js";
+const toolRegistryCache = new WeakMap;
+export function listMcpTools(engine) {
+  return getToolRegistry(engine).tools.map((tool) => tool.definition);
+}
+export async function callMcpTool(name, argumentsValue, context) {
+  const tool = getToolRegistry(context.engine).toolsByName.get(name);
+  if (tool === void 0)
+    return toolError(`Unknown tool: ${name}`);
+  try {
+    const value = await tool.call(argumentsValue ?? {}, context);
+    return toolSuccess(value);
+  } catch (error) {
+    if (error instanceof McpToolExecutionError)
+      return toolError(error.message);
+    if (error instanceof Error && error.message === "Workflow cancelled")
+      return toolError(error.message);
+    console.warn("MCP tool execution failed:", error);
+    return toolError("Tool execution failed");
+  }
+}
+function getToolRegistry(engine) {
+  const signature = toolRegistrySignature(engine), cached = toolRegistryCache.get(engine);
+  if (cached !== void 0 && toolRegistrySignaturesEqual(cached.signature, signature))
+    return cached;
+  const tools = buildToolImplementations(engine), registry = {
+    signature,
+    tools,
+    toolsByName: new Map(tools.map((tool) => [tool.definition.name, tool]))
+  };
+  toolRegistryCache.set(engine, registry);
+  return registry;
+}
+function toolRegistrySignature(engine) {
+  return engine.listWorkflowDefinitions().toSorted((left, right) => left.type < right.type ? -1 : left.type > right.type ? 1 : 0).map((definition) => [definition.type, definition.description, definition.inputSchema]);
+}
+function toolRegistrySignaturesEqual(left, right) {
+  if (left.length !== right.length)
+    return !1;
+  for (let index = 0;index < left.length; index++) {
+    const leftEntry = left[index], rightEntry = right[index];
+    if (leftEntry === void 0 || rightEntry === void 0)
+      return !1;
+    if (leftEntry[0] !== rightEntry[0] || leftEntry[1] !== rightEntry[1] || leftEntry[2] !== rightEntry[2])
+      return !1;
+  }
+  return !0;
+}
+function buildToolImplementations(engine) {
+  const tools = [...builtInTools()], usedNames = new Set(tools.map((tool) => tool.definition.name));
+  for (const definition of engine.listWorkflowDefinitions().toSorted((left, right) => left.type < right.type ? -1 : left.type > right.type ? 1 : 0)) {
+    if (definition.inputSchema === void 0)
+      continue;
+    const name = uniqueToolName(toolNameFromWorkflowType(definition.type), usedNames);
+    usedNames.add(name);
+    tools.push({
+      definition: {
+        name,
+        title: definition.type,
+        description: definition.description ?? `Run Weft workflow ${definition.type}.`,
+        inputSchema: convertWorkflowInputSchema(definition.type, definition.inputSchema)
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "workflows:write", "Calling workflow tools");
+        const input = argumentsValue, workflowId = crypto.randomUUID();
+        context.session.trackRequest(context.requestId, workflowId);
+        try {
+          if (context.session.isRequestCancelled(context.requestId))
+            throw new McpToolExecutionError("Workflow cancelled");
+          const handle = await runtimeWorkflowEngine(context.engine).start(definition.type, input, {
+            id: workflowId
+          });
+          if (context.session.isRequestCancelled(context.requestId))
+            await context.engine.cancel(handle.id);
+          const result = await handle.result();
+          return { workflowId: handle.id, result };
+        } finally {
+          context.session.untrackRequest(context.requestId);
+        }
+      }
+    });
+  }
+  return tools.toSorted((left, right) => left.definition.name < right.definition.name ? -1 : 1);
+}
+function convertWorkflowInputSchema(workflowType, schema) {
+  try {
+    return definitionSchemaToJsonSchema(schema, "input");
+  } catch (cause) {
+    throw new RegistrySchemaConversionError("workflow", workflowType, "inputSchema", cause);
+  }
+}
+function builtInTools() {
+  return [
+    {
+      definition: {
+        name: "start_workflow",
+        description: "Start a Weft workflow and return its workflow id.",
+        inputSchema: objectSchema({
+          type: { type: "string" },
+          input: {},
+          id: { type: "string" }
+        }, ["type"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "workflows:write", "Starting workflows");
+        const args = requireObject(argumentsValue), type = requireString(args.type, "type"), input = args.input ?? {}, options = typeof args.id === "string" ? { id: args.id } : void 0;
+        return { workflowId: (await runtimeWorkflowEngine(context.engine).start(type, input, options)).id };
+      }
+    },
+    {
+      definition: {
+        name: "signal_workflow",
+        description: "Send a signal to a Weft workflow.",
+        inputSchema: objectSchema({
+          workflowId: { type: "string" },
+          signalName: { type: "string" },
+          payload: {}
+        }, ["workflowId", "signalName"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "signals:write", "Signalling workflows");
+        const args = requireObject(argumentsValue), workflowId = requireString(args.workflowId, "workflowId");
+        await requireVisibleWorkflow(context, workflowId);
+        await context.engine.signal(workflowId, requireString(args.signalName, "signalName"), args.payload);
+        return { ok: !0 };
+      }
+    },
+    {
+      definition: {
+        name: "update_workflow",
+        description: "Run an update handler on a Weft workflow.",
+        inputSchema: objectSchema({
+          workflowId: { type: "string" },
+          updateName: { type: "string" },
+          payload: {}
+        }, ["workflowId", "updateName"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "updates:write", "Updating workflows");
+        const args = requireObject(argumentsValue), workflowId = requireString(args.workflowId, "workflowId");
+        await requireVisibleWorkflow(context, workflowId);
+        return { result: await context.engine.update(workflowId, requireString(args.updateName, "updateName"), args.payload) };
+      }
+    },
+    {
+      definition: {
+        name: "query_workflow",
+        description: "Run a query handler on a Weft workflow.",
+        inputSchema: objectSchema({
+          workflowId: { type: "string" },
+          queryName: { type: "string" },
+          input: {}
+        }, ["workflowId", "queryName"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "queries:read", "Querying workflows");
+        const args = requireObject(argumentsValue), workflowId = requireString(args.workflowId, "workflowId");
+        await requireVisibleWorkflow(context, workflowId);
+        return { result: await context.engine.query(workflowId, requireString(args.queryName, "queryName"), args.input) };
+      }
+    },
+    {
+      definition: {
+        name: "cancel_workflow",
+        description: "Cancel a Weft workflow.",
+        inputSchema: objectSchema({ workflowId: { type: "string" } }, ["workflowId"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "workflows:write", "Cancelling workflows");
+        const workflowId = requireString(requireObject(argumentsValue).workflowId, "workflowId");
+        await requireVisibleWorkflow(context, workflowId);
+        await context.engine.cancel(workflowId);
+        return { ok: !0 };
+      }
+    },
+    {
+      definition: {
+        name: "list_workflows",
+        description: "List visible Weft workflows.",
+        inputSchema: objectSchema({
+          status: {},
+          type: { type: "string" },
+          tags: { type: "array", items: { type: "string" } },
+          limit: { type: "number" },
+          offset: { type: "number" }
+        })
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "workflows:read", "Listing workflows");
+        const parsed = parseMcpListFilter(requireObject(argumentsValue));
+        if (!parsed.ok)
+          throw new McpToolExecutionError(parsed.message);
+        return await listVisibleWorkflows(context.engine, parsed.filter);
+      }
+    },
+    {
+      definition: {
+        name: "get_workflow_state",
+        description: "Read visible Weft workflow state.",
+        inputSchema: objectSchema({ workflowId: { type: "string" } }, ["workflowId"])
+      },
+      call: async (argumentsValue, context) => {
+        assertScope(context, "workflows:read", "Reading workflow state");
+        const workflowId = requireString(requireObject(argumentsValue).workflowId, "workflowId");
+        return await requireVisibleWorkflow(context, workflowId);
+      }
+    }
+  ];
+}
+async function requireVisibleWorkflow(context, workflowId) {
+  const state = await getVisibleWorkflowState(context.engine, workflowId);
+  if (state === null)
+    throw new McpToolExecutionError(`Workflow "${workflowId}" not found`);
+  return state;
+}
+function toolSuccess(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function toolError(message) {
+  return { isError: !0, content: [{ type: "text", text: message }] };
+}
+function requireObject(value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value))
+    return value;
+  throw new McpToolExecutionError("Tool arguments must be a JSON object");
+}
+function requireString(value, field) {
+  if (typeof value === "string" && value.length > 0)
+    return value;
+  throw new McpToolExecutionError(`Tool argument "${field}" must be a non-empty string`);
+}
+function objectSchema(properties, required = []) {
+  return {
+    type: "object",
+    properties,
+    required: [...required],
+    additionalProperties: !1
+  };
+}
+function toolNameFromWorkflowType(workflowType) {
+  const normalized = workflowType.toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replaceAll(/^_+|_+$/g, "");
+  if (/^[a-z][a-z0-9_]*$/.test(normalized))
+    return normalized;
+  return `workflow_${normalized || "unnamed"}`;
+}
+function uniqueToolName(baseName, usedNames) {
+  if (!usedNames.has(baseName))
+    return baseName;
+  let suffix = 2;
+  while (usedNames.has(`${baseName}_${String(suffix)}`))
+    suffix += 1;
+  return `${baseName}_${String(suffix)}`;
+}

package/dist/observability/activity-interceptor.d.ts

@@ -0,0 +1,3 @@
+import type { ActivityInterceptor } from '../core/interceptor';
+import type { ObservabilityState } from './types';
+export declare function buildActivityInterceptor(state: ObservabilityState): ActivityInterceptor;

package/dist/observability/activity-interceptor.js

@@ -0,0 +1,34 @@
+import { NO_OP_SPAN_METHODS } from "./no-op-telemetry.js";
+import { extractTraceParent } from "./propagation.js";
+import { runAsyncWithSpan, serializePayload } from "./span-helpers.js";
+export function buildActivityInterceptor(state) {
+  return {
+    async execute(interception, next) {
+      const parentContext = extractTraceParent(interception.headers);
+      let parentCtx = state.api.context.ROOT_CONTEXT;
+      if (parentContext) {
+        const remoteParentSpan = {
+          ...NO_OP_SPAN_METHODS,
+          spanContext() {
+            return {
+              traceId: parentContext.traceId,
+              spanId: parentContext.spanId,
+              traceFlags: parentContext.traceFlags
+            };
+          }
+        };
+        parentCtx = state.trace.setSpan(state.api.context.ROOT_CONTEXT, remoteParentSpan);
+      }
+      const span = state.tracer.startSpan(`activity:execute:${interception.activityName}`, {
+        attributes: {
+          "weft.activity.name": interception.activityName,
+          "weft.activity.attempt": interception.attempt,
+          ...parentContext ? { "weft.parent.trace_id": parentContext.traceId } : {}
+        }
+      }, parentCtx);
+      if (state.recordPayloads && interception.input !== void 0)
+        span.setAttribute("weft.payload.input", serializePayload(interception.input, state.maxPayloadSize));
+      return runAsyncWithSpan(state, span, () => next(interception));
+    }
+  };
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Observability interceptors for Weft workflows and activities.
+ *
+ * Creates an {@link Interceptor} implementation that propagates W3C trace
+ * context, emits OpenTelemetry spans, and records metrics. When
+ * `@opentelemetry/api` is not installed, all span operations are no-ops with
+ * zero overhead.
+ *
+ * @module observability
+ */
+import type { Interceptor } from '../core/interceptor';
+import { MetricsCollector as MetricsCollectorClass } from './metrics';
+import type { ObservabilityOptions } from './types';
+export { createMetricsCollectorExporter, createOpenTelemetryMetrics, METRICS, MetricsCollector, serializeMetricsSnapshotForPrometheus, } from './metrics';
+export type { CounterMetric, GaugeMetric, HistogramMetric, MetricDefinition, MetricsSnapshot, MetricType, OpenTelemetryMetrics, PrometheusExporter, } from './metrics';
+export { getOpenTelemetryApi } from './no-op-telemetry';
+export type { OpenTelemetryApi, OpenTelemetryMeter, OpenTelemetrySpan, OpenTelemetryTracer, } from './no-op-telemetry';
+export { extractTraceParent, formatTraceParent, generateSpanId, generateTraceId, injectTraceParent, parseTraceParent, } from './propagation';
+export type { TraceContext } from './propagation';
+export type { InterceptionContext, ObservabilityOptions } from './types';
+/**
+ * Create a unified interceptor for workflow and activity observability.
+ *
+ * Uses `@opentelemetry/api` directly for span creation. When the package is
+ * not installed, falls back to no-op implementations with zero overhead.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage, createObservabilityInterceptors } from '@lostgradient/weft';
+ *
+ * const { interceptor, metrics } = createObservabilityInterceptors({
+ *   tracerName: 'my-app',
+ *   recordPayloads: false,
+ * });
+ * await using engine = new Engine({
+ *   storage: new MemoryStorage(),
+ * });
+ * engine.addInterceptor(interceptor);
+ * void metrics;
+ * ```
+ */
+export declare function createObservabilityInterceptors(options?: ObservabilityOptions): {
+    interceptor: Interceptor;
+    metrics: MetricsCollectorClass;
+    /**
+     * End the workflow root span. Usually wired automatically via `eventTarget`,
+     * but exposed for callers that need to end spans manually.
+     */
+    endWorkflowSpan: (workflowId: string, status: 'ok' | 'error', errorMessage?: string) => void;
+    /**
+     * Evict workflow spans that have been open longer than `maxAgeMs` (default: 1 hour).
+     * Call periodically to prevent unbounded growth from orphaned or long-running workflows.
+     */
+    evictStaleSpans: (maxAgeMs?: number) => number;
+    /**
+     * Unsubscribe any workflow lifecycle listeners registered on the `eventTarget`
+     * and end any still-open workflow spans.
+     */
+    dispose: () => void;
+};

package/dist/observability/index.js

@@ -0,0 +1,4 @@
+// @bun
+var OS=Object.defineProperty;var PS=(S)=>S;function bS(S,$){this[S]=PS.bind(null,$)}var eS=(S,$)=>{for(var G in $)OS(S,G,{get:$[G],enumerable:!0,configurable:!0,set:bS.bind($,G)})};var Q=(S,$)=>()=>(S&&($=S(S=0)),$);var m,d,i,n;var o=Q(()=>{m=class m extends Event{static type="activity:started";operationId;workflowId;activityName;attempt;constructor(S,$,G,K){super(m.type);this.operationId=S,this.workflowId=$,this.activityName=G,this.attempt=K}};d=class d extends Event{static type="activity:completed";operationId;workflowId;activityName;duration;constructor(S,$,G,K){super(d.type);this.operationId=S,this.workflowId=$,this.activityName=G,this.duration=K}};i=class i extends Event{static type="activity:async-pending";token;operationId;workflowId;activityName;attempt;constructor(S,$,G,K,L){super(i.type);this.token=S,this.operationId=$,this.workflowId=G,this.activityName=K,this.attempt=L}};n=class n extends Event{static type="activity:failed";operationId;workflowId;activityName;error;attempt;constructor(S,$,G,K,L){super(n.type);this.operationId=S,this.workflowId=$,this.activityName=G,this.error=K,this.attempt=L}}});var l;var r=Q(()=>{l=class l extends Event{static type="attributes:changed";workflowId;changes;constructor(S,$){super(l.type);this.workflowId=S,this.changes=$}}});var s,a;var t=Q(()=>{s=class s extends Event{static type="signal:received";workflowId;signalName;payload;constructor(S,$,G){super(s.type);this.workflowId=S,this.signalName=$,this.payload=G}};a=class a extends Event{static type="signal:delivered";workflowId;signalName;constructor(S,$){super(a.type);this.workflowId=S,this.signalName=$}}});var e,SS,$S,GS,KS,LS,xS;var WS=Q(()=>{e=class e extends Event{static type="checkpoint:size-warning";workflowId;sizeBytes;step;constructor(S,$,G){super(e.type);this.workflowId=S,this.sizeBytes=$,this.step=G}};SS=class SS extends Event{static type="development:warning";workflowId;message;fieldPaths;constructor(S,$,G){super(SS.type);this.workflowId=S,this.message=$,this.fieldPaths=G}};$S=class $S extends Event{static type="cleanup:warning";source;error;workflowId;constructor(S,$,G){super($S.type);this.source=S,this.error=$,this.workflowId=G}};GS=class GS extends Event{static type="storage:size-reported";sizeBytes;constructor(S){super(GS.type);this.sizeBytes=S}};KS=class KS extends Event{static type="alert:fired";metric;threshold;currentValue;window;constructor(S,$,G,K){super(KS.type);this.metric=S,this.threshold=$,this.currentValue=G,this.window=K}};LS=class LS extends Event{static type="alert:resolved";metric;threshold;currentValue;window;constructor(S,$,G,K){super(LS.type);this.metric=S,this.threshold=$,this.currentValue=G,this.window=K}};xS=class xS extends Event{static type="constraint:violated";workflowId;constraintName;scope;onViolation;constructor(S,$,G,K){super(xS.type);this.workflowId=S,this.constraintName=$,this.scope=G,this.onViolation=K}}});var XS,TS;var JS=Q(()=>{XS=class XS extends Event{static type="update:received";updateId;workflowId;name;payload;constructor(S,$,G,K){super(XS.type);this.updateId=S,this.workflowId=$,this.name=G,this.payload=K}};TS=class TS extends Event{static type="update:completed";updateId;workflowId;name;result;error;constructor(S,$,G,K,L){super(TS.type);this.updateId=S,this.workflowId=$,this.name=G,this.result=K,this.error=L}}});var QS,j,q,H,Y,B0,jS,qS;var HS=Q(()=>{QS=class QS extends Event{static type="workflow:started";workflowId;workflowType;input;constructor(S,$,G){super(QS.type);this.workflowId=S,this.workflowType=$,this.input=G}};j=class j extends Event{static type="workflow:completed";workflowId;result;duration;constructor(S,$,G){super(j.type);this.workflowId=S,this.result=$,this.duration=G}};q=class q extends Event{static type="workflow:failed";workflowId;error;constructor(S,$){super(q.type);this.workflowId=S,this.error=$}};H=class H extends Event{static type="workflow:cancelled";workflowId;constructor(S){super(H.type);this.workflowId=S}};Y=class Y extends Event{static type="workflow:timed-out";workflowId;timeoutType;elapsed;reason;constructor(S,$,G,K){super(Y.type);if(this.workflowId=S,this.timeoutType=$,this.elapsed=G,K!==void 0)this.reason=K}};B0=new Set([j.type,q.type,H.type,Y.type]);jS=class jS extends Event{static type="workflow:resumed";workflowId;fromStep;constructor(S,$){super(jS.type);this.workflowId=S,this.fromStep=$}};qS=class qS extends Event{static type="workflow:recovery-skipped";workflowId;workflowType;reason;constructor(S,$,G){super(qS.type);this.workflowId=S,this.workflowType=$,this.reason=G}}});var YS=Q(()=>{o();r();t();WS();JS();HS()});var ZS=Q(()=>{YS()});var DS={traceId:"0".repeat(32),spanId:"0".repeat(16),traceFlags:0},P={setAttribute(){},setStatus(){},recordException(){},end(){},spanContext(){return DS}},z={setAttribute:(...S)=>P.setAttribute(...S),setStatus:(...S)=>P.setStatus(...S),recordException:(...S)=>P.recordException(...S),end:(...S)=>P.end(...S)},US={startSpan(){return P}},V={record(){},add(){}},_S={createHistogram(){return V},createCounter(){return V},createUpDownCounter(){return V}},yS=Symbol("ROOT_CONTEXT"),RS={trace:{getTracer(){return US},setSpan(S){return S}},metrics:{getMeter(){return _S}},context:{ROOT_CONTEXT:yS,with(S,$){return $()}},SpanStatusCode:{OK:1,ERROR:2,UNSET:0}},M;function AS(){let S=globalThis.require;if(typeof S==="function")return($)=>S($);return()=>{return}}function VS(S){return S?.trace?.getTracer!=null&&S.SpanStatusCode!=null}function fS(S=AS()){try{let $=S("@opentelemetry/api");if(VS($))return $}catch{}return}function k(S){if(M)return M;let $=fS(S);if($)return M=$,M;return M=RS,M}function I(S){let $=new Uint8Array(S);return crypto.getRandomValues($),Array.from($,(G)=>G.toString(16).padStart(2,"0")).join("")}var N="traceparent",CS=/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/,zS="00000000000000000000000000000000",IS="0000000000000000";function p(S){let $=CS.exec(S);if(!$)return null;let[,G,K,L,W]=$;if(K===zS)return null;if(L===IS)return null;return{version:G,traceId:K,spanId:L,traceFlags:parseInt(W,16)}}function g(S){let $=S.traceFlags.toString(16).padStart(2,"0");return`${S.version}-${S.traceId}-${S.spanId}-${$}`}function b(S){let $=S.get(N);if(!$)return null;return p($)}function f(S,$){S.set(N,g($))}function NS(){return I(16)}function pS(){return I(8)}var u=1024;function w(S,$){let G;try{G=JSON.stringify(S)}catch{G=String(S)}if(G.length>$)return G.slice(0,$)+"...";return G}function gS(S){return S instanceof Error?S.message:String(S)}function uS(S){return S instanceof Error?S:Error(String(S))}function D(S,$){let G=S.spanContext();f($,{version:"00",traceId:G.traceId,spanId:G.spanId,traceFlags:G.traceFlags})}function B(S,$,G){let K=S.attributeExtractor;if(!K)return;let L=K(G);for(let[W,X]of Object.entries(L))$.setAttribute(W,X)}function U(S,$){let G=S.workflowSpans.get($);return G?S.trace.setSpan(S.api.context.ROOT_CONTEXT,G.span):S.api.context.ROOT_CONTEXT}function C(S,$,G){$.setStatus({code:S.SpanStatusCode.ERROR,message:gS(G)}),$.recordException(uS(G))}function h(S,$,G,K){try{let L=G();return $.setStatus({code:S.SpanStatusCode.OK}),K?.(L),L}catch(L){throw C(S,$,L),L}finally{$.end()}}async function _(S,$,G,K){try{let L=await G();return $.setStatus({code:S.SpanStatusCode.OK}),K?.(L),L}catch(L){throw C(S,$,L),L}finally{$.end()}}function*y(S,$,G,K){try{let L=yield*G();return $.setStatus({code:S.SpanStatusCode.OK}),K?.(L),L}catch(L){throw C(S,$,L),L}finally{$.end()}}function E(S){return{async execute($,G){let K=b($.headers),L=S.api.context.ROOT_CONTEXT;if(K){let X={...z,spanContext(){return{traceId:K.traceId,spanId:K.spanId,traceFlags:K.traceFlags}}};L=S.trace.setSpan(S.api.context.ROOT_CONTEXT,X)}let W=S.tracer.startSpan(`activity:execute:${$.activityName}`,{attributes:{"weft.activity.name":$.activityName,"weft.activity.attempt":$.attempt,...K?{"weft.parent.trace_id":K.traceId}:{}}},L);if(S.recordPayloads&&$.input!==void 0)W.setAttribute("weft.payload.input",w($.input,S.maxPayloadSize));return _(S,W,()=>G($))}}}var F={workflowDuration:{name:"weft.workflow.duration",description:"Duration of workflow execution in milliseconds",unit:"ms",type:"histogram"},activityDuration:{name:"weft.activity.duration",description:"Duration of activity execution in milliseconds",unit:"ms",type:"histogram"},activityAttempts:{name:"weft.activity.attempts",description:"Total activity execution attempts",unit:"attempts",type:"counter"},workflowActive:{name:"weft.workflow.active",description:"Number of currently active workflows",unit:"workflows",type:"gauge"},workflowStarted:{name:"weft.workflow.started",description:"Total workflows started",unit:"workflows",type:"counter"},workflowCompleted:{name:"weft.workflow.completed",description:"Total workflows completed",unit:"workflows",type:"counter"},workflowFailed:{name:"weft.workflow.failed",description:"Total workflows failed",unit:"workflows",type:"counter"},promptCacheHits:{name:"weft.prompt_cache.hits",description:"Total prompt prefix cache hits",unit:"hits",type:"counter"},promptCacheMisses:{name:"weft.prompt_cache.misses",description:"Total prompt prefix cache misses",unit:"misses",type:"counter"},dpmoDefects:{name:"weft.dpmo.defects",description:"Total failed workflows (DPMO numerator)",unit:"workflows",type:"counter"},dpmoOperations:{name:"weft.dpmo.operations",description:"Total started workflows (DPMO denominator)",unit:"workflows",type:"counter"},taskBacklog:{name:"weft.task.backlog",description:"Number of queued tasks waiting for workers",unit:"tasks",type:"gauge"},taskQueueLatency:{name:"weft.task.queue_latency",description:"Time tasks spend queued before dispatch in milliseconds",unit:"ms",type:"histogram"},taskExecutionLatency:{name:"weft.task.execution_latency",description:"Time tasks spend executing after worker start in milliseconds",unit:"ms",type:"histogram"},taskRetries:{name:"weft.task.retries",description:"Total task retry attempts after the first dispatch attempt",unit:"retries",type:"counter"},taskRequeues:{name:"weft.task.requeues",description:"Total visibility-timeout or disconnect task requeues",unit:"requeues",type:"counter"},taskStaleHeartbeats:{name:"weft.task.stale_heartbeats",description:"Number of in-flight tasks whose heartbeat age exceeds the diagnostic threshold",unit:"tasks",type:"gauge"},workerCapacitySaturation:{name:"weft.worker.capacity_saturation",description:"Ratio of in-flight worker slots to total worker concurrency",unit:"ratio",type:"gauge"}};var hS=1e4;class v{#S;#G=0;#$=0;constructor(S){this.#S=new Float64Array(S)}push(S){if(this.#S[this.#G]=S,this.#G=(this.#G+1)%this.#S.length,this.#$<this.#S.length)this.#$++}toArray(){if(this.#$<this.#S.length)return Array.from(this.#S.subarray(0,this.#$));let S=Array.from({length:this.#$});for(let $=0;$<this.#$;$++)S[$]=this.#S[(this.#G+$)%this.#S.length];return S}}class R{#S;#G;#$;constructor(){this.#S=new Map,this.#G=new Map,this.#$=new Map}increment(S,$=1){this.#S.set(S,(this.#S.get(S)??0)+$)}record(S,$){let G=this.#G.get(S);if(!G)G=new v(hS),this.#G.set(S,G);G.push($)}gauge(S,$){this.#$.set(S,$)}snapshot(){let S={};for(let[$,G]of this.#S)S[$]={type:"counter",value:G};for(let[$,G]of this.#G){let K=G.toArray(),L=vS(K);S[$]={type:"histogram",count:K.length,sum:cS(K),p50:L[Math.floor(L.length*0.5)]??0,p99:L[Math.floor(L.length*0.99)]??0,min:L[0]??0,max:L[L.length-1]??0}}for(let[$,G]of this.#$)S[$]={type:"gauge",value:G};return S}reset(){this.#S.clear(),this.#G.clear(),this.#$.clear()}}function ES(S){let $;if(typeof S==="string")$=k().metrics.getMeter(S);else if(S)$=S;else $=k().metrics.getMeter("weft");return{workflowDuration:$.createHistogram("weft.workflow.duration",{unit:"ms"}),activityDuration:$.createHistogram("weft.activity.duration",{unit:"ms"}),activityAttempts:$.createCounter("weft.activity.attempts"),activeWorkflows:$.createUpDownCounter("weft.workflow.active")}}function vS(S){let $=[...S];return $.sort((G,K)=>G-K),$}function cS(S){let $=0;for(let G of S)$+=G;return $}function mS(S,$){let G=$?.type==="histogram"?$.count:0,K=$?.type==="histogram"?$.sum:0;return[`# TYPE ${S} histogram`,`${S}_count ${G}`,`${S}_sum ${K}`]}function dS(S,$){let G=$?.type==="counter"?$.value:0;return[`# TYPE ${S} counter`,`${S}_total ${G}`]}function iS(S,$){let G=$?.type==="gauge"?$.value:0;return[`# TYPE ${S} gauge`,`${S} ${G}`]}var nS={histogram:mS,counter:dS,gauge:iS};function oS(S,$){let G=S.name.replace(/\./g,"_"),K=$[S.name];return[`# HELP ${G} ${S.description}`,...nS[S.type](G,K)]}function lS(S){let $=S[F.dpmoDefects.name],G=S[F.dpmoOperations.name],K=$?.type==="counter"?$.value:0,L=G?.type==="counter"?G.value:0,W=L===0?0:K*1e6/L,X="weft_dpmo";return["# HELP weft_dpmo Defects per million operations (failed workflows / started workflows * 1e6)","# TYPE weft_dpmo gauge",`weft_dpmo ${W}`]}function c(S){let $=[];for(let G of Object.values(F))$.push(...oS(G,S));return $.push(...lS(S)),$.join(`
+`)+`
+`}function rS(S){return{serialize(){let $=S?.snapshot()??{};return c($)}}}ZS();var sS=3600000,MS=1e4,aS=3600000;function kS(S){let $=Date.now();for(let[G,K]of S.workflowSpans)if($-K.createdAt>sS)K.span.end(),S.workflowSpans.delete(G);if(S.workflowSpans.size>MS){let G=S.workflowSpans.size-MS,K=0;for(let[L,W]of S.workflowSpans){if(K>=G)break;W.span.end(),S.workflowSpans.delete(L),K++}}}function wS(S,$){let G=S.workflowSpans.get($);if(G)G.span.end(),S.workflowSpans.delete($)}function BS(S){function $(x,Z,T){let J=S.workflowSpans.get(x);if(!J)return;if(Z==="error")J.span.setStatus({code:S.SpanStatusCode.ERROR,...T?{message:T}:{}});else J.span.setStatus({code:S.SpanStatusCode.OK});J.span.end(),S.workflowSpans.delete(x)}let G=(x)=>{if(!(x instanceof j))return;$(x.workflowId,"ok")},K=(x)=>{if(!(x instanceof q))return;$(x.workflowId,"error",x.error.message),S.metrics.increment("weft.dpmo.defects")},L=(x)=>{if(!(x instanceof H))return;$(x.workflowId,"error","Workflow cancelled")},W=(x)=>{if(!(x instanceof Y))return;$(x.workflowId,"error",`Workflow timed out (${x.timeoutType}) after ${x.elapsed}ms`),S.metrics.increment("weft.dpmo.defects")};if(S.eventTarget)S.eventTarget.addEventListener(j.type,G),S.eventTarget.addEventListener(q.type,K),S.eventTarget.addEventListener(H.type,L),S.eventTarget.addEventListener(Y.type,W);function X(x=aS){let Z=Date.now()-x,T=0;for(let[J,O]of S.workflowSpans)if(O.createdAt<=Z)O.span.setStatus({code:S.SpanStatusCode.ERROR,message:"span evicted (stale)"}),O.span.end(),S.workflowSpans.delete(J),T++;return T}function A(){if(S.eventTarget)S.eventTarget.removeEventListener(j.type,G),S.eventTarget.removeEventListener(q.type,K),S.eventTarget.removeEventListener(H.type,L),S.eventTarget.removeEventListener(Y.type,W);for(let x of S.workflowSpans.values())x.span.setStatus({code:S.SpanStatusCode.ERROR,message:"Observability disposed"}),x.span.end();S.workflowSpans.clear()}return{endWorkflowSpan:$,evictStaleSpans:X,dispose:A}}function FS(S){return{workflowStart($,G){kS(S);let K=S.workflowSpans.get($.workflowId);if(K)K.span.setStatus({code:S.SpanStatusCode.OK}),wS(S,$.workflowId);let L=S.tracer.startSpan(`workflow:${$.workflowType}`,{attributes:{"weft.workflow.id":$.workflowId,"weft.workflow.type":$.workflowType}});if(S.workflowSpans.set($.workflowId,{span:L,createdAt:Date.now()}),D(L,$.headers),S.recordPayloads&&$.input!==void 0)L.setAttribute("weft.payload.input",w($.input,S.maxPayloadSize));B(S,L,$),S.metrics.increment("weft.workflow.started"),S.metrics.increment("weft.dpmo.operations"),G($)},*activity($,G){let K=S.tracer.startSpan(`activity:${$.activityName}`,{attributes:{"weft.activity.name":$.activityName,"weft.activity.attempt":$.attempt}},U(S,$.workflowId));if(D(K,$.headers),S.recordPayloads&&$.input!==void 0)K.setAttribute("weft.payload.input",w($.input,S.maxPayloadSize));B(S,K,$);let L=Date.now();return yield*y(S,K,()=>G($),()=>{S.metrics.record("weft.activity.duration",Date.now()-L),S.metrics.increment("weft.activity.attempts")})},*sleep($,G){let K=S.tracer.startSpan("sleep",{attributes:{"weft.sleep.duration":$.duration}},U(S,$.workflowId));B(S,K,$),yield*y(S,K,()=>G($))},*waitForSignal($,G){let K=S.tracer.startSpan("waitForSignal",{attributes:{"weft.signal.name":$.signalName}},U(S,$.workflowId));return B(S,K,$),yield*y(S,K,()=>G($))},async childWorkflow($,G){let K=[],L=b($.parentHeaders);if(L)K.push({context:{traceId:L.traceId,spanId:L.spanId,traceFlags:L.traceFlags}});let W=S.tracer.startSpan(`childWorkflow:${$.workflowType}`,{attributes:{"weft.child_workflow.type":$.workflowType,"weft.child_workflow.id":$.childWorkflowId,"weft.child_workflow.parent_id":$.workflowId},links:K},S.api.context.ROOT_CONTEXT);if(D(W,$.headers),S.recordPayloads&&$.input!==void 0)W.setAttribute("weft.payload.input",w($.input,S.maxPayloadSize));return S.metrics.increment("weft.child_workflow.started"),_(S,W,()=>G($))},signalReceived($,G){let K=S.tracer.startSpan(`signal:received:${$.signalName}`,{attributes:{"weft.signal.name":$.signalName,"weft.signal.workflow_id":$.workflowId}});B(S,K,$),h(S,K,()=>G($))}}}function tS(S){let{attributeExtractor:$,eventTarget:G,maxPayloadSize:K=u,metrics:L=new R,openTelemetryApi:W=k(),recordPayloads:X=!1,tracerName:A="weft",tracerVersion:x}=S??{},Z=W,{trace:T,SpanStatusCode:J}=Z,O=T.getTracer(A,x);return{api:Z,trace:T,SpanStatusCode:J,tracer:O,recordPayloads:X,maxPayloadSize:K,attributeExtractor:$,eventTarget:G,metrics:L,workflowSpans:new Map}}function m0(S){let $=tS(S),G=FS($),K=E($),L={...G,...K},W=BS($);return{interceptor:L,metrics:$.metrics,...W}}export{c as serializeMetricsSnapshotForPrometheus,p as parseTraceParent,f as injectTraceParent,k as getOpenTelemetryApi,NS as generateTraceId,pS as generateSpanId,g as formatTraceParent,b as extractTraceParent,ES as createOpenTelemetryMetrics,m0 as createObservabilityInterceptors,rS as createMetricsCollectorExporter,R as MetricsCollector,F as METRICS};

package/dist/observability/metrics-catalog.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Metric catalogue for Weft observability.
+ *
+ * @module metrics-catalog
+ */
+/**
+ * Metric names and descriptions for Weft observability.
+ *
+ * @example
+ * ```ts
+ * import { METRICS } from '@lostgradient/weft/observability';
+ *
+ * for (const metric of Object.values(METRICS)) {
+ *   console.log(metric.name, metric.type, metric.unit);
+ * }
+ * // e.g. 'weft.workflow.duration' 'histogram' 'ms'
+ * ```
+ */
+export declare const METRICS: {
+    readonly workflowDuration: {
+        readonly name: "weft.workflow.duration";
+        readonly description: "Duration of workflow execution in milliseconds";
+        readonly unit: "ms";
+        readonly type: "histogram";
+    };
+    readonly activityDuration: {
+        readonly name: "weft.activity.duration";
+        readonly description: "Duration of activity execution in milliseconds";
+        readonly unit: "ms";
+        readonly type: "histogram";
+    };
+    readonly activityAttempts: {
+        readonly name: "weft.activity.attempts";
+        readonly description: "Total activity execution attempts";
+        readonly unit: "attempts";
+        readonly type: "counter";
+    };
+    readonly workflowActive: {
+        readonly name: "weft.workflow.active";
+        readonly description: "Number of currently active workflows";
+        readonly unit: "workflows";
+        readonly type: "gauge";
+    };
+    readonly workflowStarted: {
+        readonly name: "weft.workflow.started";
+        readonly description: "Total workflows started";
+        readonly unit: "workflows";
+        readonly type: "counter";
+    };
+    readonly workflowCompleted: {
+        readonly name: "weft.workflow.completed";
+        readonly description: "Total workflows completed";
+        readonly unit: "workflows";
+        readonly type: "counter";
+    };
+    readonly workflowFailed: {
+        readonly name: "weft.workflow.failed";
+        readonly description: "Total workflows failed";
+        readonly unit: "workflows";
+        readonly type: "counter";
+    };
+    readonly promptCacheHits: {
+        readonly name: "weft.prompt_cache.hits";
+        readonly description: "Total prompt prefix cache hits";
+        readonly unit: "hits";
+        readonly type: "counter";
+    };
+    readonly promptCacheMisses: {
+        readonly name: "weft.prompt_cache.misses";
+        readonly description: "Total prompt prefix cache misses";
+        readonly unit: "misses";
+        readonly type: "counter";
+    };
+    readonly dpmoDefects: {
+        readonly name: "weft.dpmo.defects";
+        readonly description: "Total failed workflows (DPMO numerator)";
+        readonly unit: "workflows";
+        readonly type: "counter";
+    };
+    readonly dpmoOperations: {
+        readonly name: "weft.dpmo.operations";
+        readonly description: "Total started workflows (DPMO denominator)";
+        readonly unit: "workflows";
+        readonly type: "counter";
+    };
+    readonly taskBacklog: {
+        readonly name: "weft.task.backlog";
+        readonly description: "Number of queued tasks waiting for workers";
+        readonly unit: "tasks";
+        readonly type: "gauge";
+    };
+    readonly taskQueueLatency: {
+        readonly name: "weft.task.queue_latency";
+        readonly description: "Time tasks spend queued before dispatch in milliseconds";
+        readonly unit: "ms";
+        readonly type: "histogram";
+    };
+    readonly taskExecutionLatency: {
+        readonly name: "weft.task.execution_latency";
+        readonly description: "Time tasks spend executing after worker start in milliseconds";
+        readonly unit: "ms";
+        readonly type: "histogram";
+    };
+    readonly taskRetries: {
+        readonly name: "weft.task.retries";
+        readonly description: "Total task retry attempts after the first dispatch attempt";
+        readonly unit: "retries";
+        readonly type: "counter";
+    };
+    readonly taskRequeues: {
+        readonly name: "weft.task.requeues";
+        readonly description: "Total visibility-timeout or disconnect task requeues";
+        readonly unit: "requeues";
+        readonly type: "counter";
+    };
+    readonly taskStaleHeartbeats: {
+        readonly name: "weft.task.stale_heartbeats";
+        readonly description: "Number of in-flight tasks whose heartbeat age exceeds the diagnostic threshold";
+        readonly unit: "tasks";
+        readonly type: "gauge";
+    };
+    readonly workerCapacitySaturation: {
+        readonly name: "weft.worker.capacity_saturation";
+        readonly description: "Ratio of in-flight worker slots to total worker concurrency";
+        readonly unit: "ratio";
+        readonly type: "gauge";
+    };
+};

package/dist/observability/metrics-catalog.js

@@ -0,0 +1,110 @@
+export const METRICS = {
+  workflowDuration: {
+    name: "weft.workflow.duration",
+    description: "Duration of workflow execution in milliseconds",
+    unit: "ms",
+    type: "histogram"
+  },
+  activityDuration: {
+    name: "weft.activity.duration",
+    description: "Duration of activity execution in milliseconds",
+    unit: "ms",
+    type: "histogram"
+  },
+  activityAttempts: {
+    name: "weft.activity.attempts",
+    description: "Total activity execution attempts",
+    unit: "attempts",
+    type: "counter"
+  },
+  workflowActive: {
+    name: "weft.workflow.active",
+    description: "Number of currently active workflows",
+    unit: "workflows",
+    type: "gauge"
+  },
+  workflowStarted: {
+    name: "weft.workflow.started",
+    description: "Total workflows started",
+    unit: "workflows",
+    type: "counter"
+  },
+  workflowCompleted: {
+    name: "weft.workflow.completed",
+    description: "Total workflows completed",
+    unit: "workflows",
+    type: "counter"
+  },
+  workflowFailed: {
+    name: "weft.workflow.failed",
+    description: "Total workflows failed",
+    unit: "workflows",
+    type: "counter"
+  },
+  promptCacheHits: {
+    name: "weft.prompt_cache.hits",
+    description: "Total prompt prefix cache hits",
+    unit: "hits",
+    type: "counter"
+  },
+  promptCacheMisses: {
+    name: "weft.prompt_cache.misses",
+    description: "Total prompt prefix cache misses",
+    unit: "misses",
+    type: "counter"
+  },
+  dpmoDefects: {
+    name: "weft.dpmo.defects",
+    description: "Total failed workflows (DPMO numerator)",
+    unit: "workflows",
+    type: "counter"
+  },
+  dpmoOperations: {
+    name: "weft.dpmo.operations",
+    description: "Total started workflows (DPMO denominator)",
+    unit: "workflows",
+    type: "counter"
+  },
+  taskBacklog: {
+    name: "weft.task.backlog",
+    description: "Number of queued tasks waiting for workers",
+    unit: "tasks",
+    type: "gauge"
+  },
+  taskQueueLatency: {
+    name: "weft.task.queue_latency",
+    description: "Time tasks spend queued before dispatch in milliseconds",
+    unit: "ms",
+    type: "histogram"
+  },
+  taskExecutionLatency: {
+    name: "weft.task.execution_latency",
+    description: "Time tasks spend executing after worker start in milliseconds",
+    unit: "ms",
+    type: "histogram"
+  },
+  taskRetries: {
+    name: "weft.task.retries",
+    description: "Total task retry attempts after the first dispatch attempt",
+    unit: "retries",
+    type: "counter"
+  },
+  taskRequeues: {
+    name: "weft.task.requeues",
+    description: "Total visibility-timeout or disconnect task requeues",
+    unit: "requeues",
+    type: "counter"
+  },
+  taskStaleHeartbeats: {
+    name: "weft.task.stale_heartbeats",
+    description: "Number of in-flight tasks whose heartbeat age exceeds the diagnostic threshold",
+    unit: "tasks",
+    type: "gauge"
+  },
+  workerCapacitySaturation: {
+    name: "weft.worker.capacity_saturation",
+    description: "Ratio of in-flight worker slots to total worker concurrency",
+    unit: "ratio",
+    type: "gauge"
+  }
+};