@yarlisai/core

Shared primitives — env helpers, logger, streaming types, trace types.

Install

npm install @yarlisai/core

Why

@yarlisai/core follows the port/adapter contract: consumers depend on a port (SomeProvider interface) and instantiate an adapter at runtime. Swapping vendors is a single-line config change.

Usage

The package's README ships a complete quickstart. mybotbox-platform itself is the reference consumer — apps/sat/lib/core/ (or a similarly-named module) shows how every callsite uses the port instead of a vendor SDK directly.

Trace span transforms

The @yarlisai/core/trace subpath ships the portable execution-trace primitives: the TraceSpan / ToolCall types plus the pure span-tree transforms that normalize a trace before display or storage. Every transform operates exclusively on TraceSpan trees — no executor or app imports — so any runtime that produces trace spans can reuse the same pipeline.

import {
  ensureNestedWorkflowsProcessed,
  flattenWorkflowChildren,
  getTraceSpanKey,
  groupIterationBlocks,
  isSyntheticWorkflowWrapper,
  mergeTraceSpanChildren,
  stripCustomToolPrefix,
  type TraceSpan,
} from '@yarlisai/core/trace'

// Unwrap synthetic "Workflow Execution" wrappers from child-workflow traces
const children = flattenWorkflowChildren(childTraceSpans)

// Merge child groups, deduped by span identity (id, or name + time range)
const merged = mergeTraceSpanChildren(existingChildren, children)

// Fold "<name> (iteration <n>)" spans into loop/parallel iteration containers
const rootSpans = groupIterationBlocks(merged)

• flattenWorkflowChildren(spans) — unwraps synthetic workflow wrappers recursively and normalizes nested child-workflow spans.
• mergeTraceSpanChildren(...groups) — merges span groups, deduping by getTraceSpanKey (earlier groups win).
• groupIterationBlocks(spans) — groups loop/parallel iteration spans into per-iteration containers, sorted by start time.
• ensureNestedWorkflowsProcessed(span) — hoists output.childTraceSpans into children (deduped) and strips them from the output payload.
• isSyntheticWorkflowWrapper(span) / getTraceSpanKey(span) / stripCustomToolPrefix(name) — the small predicates the pipeline is built from.

Mapping a concrete execution result into spans stays product-side: in MyBotBox, apps/sat/lib/logs/execution/trace-spans/trace-spans.ts keeps buildTraceSpans(result) (it knows about executor BlockLogs and the isWorkflowBlockType predicate) and composes these transforms.

See also

• Source
• npm
• ADR 0007 — Port/adapter contract