@output.ai/core 0.0.15 → 0.1.0

package/src/interface/validations/static.js

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import { isZodSchema } from '../schema_utils.js';
+import { isZodSchema } from './schema_utils.js';
 
 /**
  * Error is thrown when the definition of a step/workflow has problems
@@ -25,6 +25,8 @@ const stepAndWorkflowSchema = z.object( {
   fn: z.function()
 } );
 
+const evaluatorSchema = stepAndWorkflowSchema.omit( { outputSchema: true } );
+
 const webhookSchema = z.object( {
   url: z.url( { protocol: /^https?$/ } ),
   payload: z.any().optional()
@@ -47,6 +49,16 @@ export function validateStep( args ) {
   validateAgainstSchema( stepAndWorkflowSchema, args );
 };
 
+/**
+ * Validate evaluator payload
+ *
+ * @param {object} args - The evaluator arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateEvaluator( args ) {
+  validateAgainstSchema( evaluatorSchema, args );
+};
+
 /**
  * Validate workflow payload
  *

package/src/interface/validations/static.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
-import { validateStep, validateWorkflow, validateCreateWebhook, StaticValidationError } from './static.js';
+import { validateStep, validateWorkflow, validateCreateWebhook, validateEvaluator, StaticValidationError } from './static.js';
 
 const validArgs = Object.freeze( {
   name: 'valid_name',
@@ -73,6 +73,34 @@ describe( 'interface/validator', () => {
     } );
   } );
 
+  describe( 'validateEvaluator', () => {
+    const base = Object.freeze( {
+      name: 'valid_name',
+      description: 'desc',
+      inputSchema: z.object( {} ),
+      fn: () => {}
+    } );
+
+    it( 'passes for valid args (no outputSchema)', () => {
+      expect( () => validateEvaluator( { ...base } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateEvaluator( { ...base, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateEvaluator( { ...base, inputSchema: 'not-a-zod-schema' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateEvaluator( { ...base, fn: undefined } ) ).toThrow( error );
+    } );
+  } );
+
   describe( 'validate webhook', () => {
     it( 'passes with valid http url', () => {
       expect( () => validateCreateWebhook( { url: 'http://example.com' } ) ).not.toThrow();

package/src/interface/webhook.js

@@ -1,18 +1,30 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { defineSignal, setHandler, proxyActivities, workflowInfo } from '@temporalio/workflow';
-import { SEND_WEBHOOK_ACTIVITY_NAME } from '#consts';
+import { defineSignal, setHandler, proxyActivities, workflowInfo, proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_SEND_WEBHOOK } from '#consts';
+import { FatalError } from '#errors';
 import { validateCreateWebhook } from './validations/static.js';
 
 export async function createWebhook( { url, payload } ) {
   validateCreateWebhook( { url, payload } );
-  const workflowId = workflowInfo();
+  const { workflowId } = workflowInfo();
 
-  await proxyActivities( temporalActivityConfigs )[SEND_WEBHOOK_ACTIVITY_NAME]( { url, workflowId, payload } );
+  await proxyActivities( {
+    startToCloseTimeout: '3m',
+    retry: {
+      initialInterval: '15s',
+      maximumAttempts: 5,
+      nonRetryableErrorTypes: [ FatalError.name ]
+    }
+  } )[ACTIVITY_SEND_WEBHOOK]( { url, workflowId, payload } );
 
+  const sinks = await proxySinks();
   const resumeSignal = defineSignal( 'resume' );
 
+  const traceId = `${workflowId}-${url}-${Date.now()}`;
+  sinks.trace.addEventStart( { id: traceId, name: 'resume', kind: 'webhook' } );
   return new Promise( resolve =>
     setHandler( resumeSignal, responsePayload => {
+      sinks.trace.addEventEnd( { id: traceId, details: responsePayload } );
       resolve( responsePayload );
     } )
   );

package/src/interface/workflow.js

@@ -1,11 +1,11 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, ApplicationFailure, proxySinks } from '@temporalio/workflow';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo } from '@temporalio/workflow';
 import { getInvocationDir } from './utils.js';
 import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '#errors';
 import { validateWorkflow } from './validations/static.js';
-import { READ_TRACE_FILE, TraceEvent } from '#consts';
-import { validateWithSchema } from './schema_utils.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ACTIVITY_READ_TRACE_FILE } from '#consts';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -19,71 +19,49 @@ const temporalActivityConfigs = {
 };
 
 export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
-  validateWorkflow( {
-    name,
-    description,
-    inputSchema,
-    outputSchema,
-    fn
-  } );
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
-  const sinks = proxySinks();
 
   const wrapper = async input => {
-    try {
-      if ( inWorkflowContext() ) {
-        sinks.log.trace( { event: TraceEvent.WORKFLOW_START, input } );
-      }
-
-      validateWithSchema( inputSchema, input, `Workflow ${name} input` );
-
-      // this returns a plain function, for example, in unit tests
-      if ( !inWorkflowContext() ) {
-        const output = await fn( input );
-        validateWithSchema( outputSchema, output, `Workflow ${name} output` );
-        return output;
-      }
-
-      const { memo, workflowId } = workflowInfo();
-
-      Object.assign( workflowInfo().memo, { workflowPath } );
-
-      // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
-      const output = await fn.call( {
-        invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
 
-        startWorkflow: async ( childName, input ) => {
+    // this returns a plain function, for example, in unit tests
+    if ( !inWorkflowContext() ) {
+      const output = await fn( input );
+      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+      return output;
+    }
 
-          // Checks if current memo has rootWorkflowId, which means current execution is already a child
-          // Then it sets the memory for the child execution passing along who's the original workflow is and its type
-          const workflowMemory = memo.rootWorkflowId ?
-            { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
-            { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: name };
+    const { workflowId, memo } = workflowInfo();
 
-          return executeChild( childName, { args: input ? [ input ] : [], memo: workflowMemory } );
-        }
-      }, input );
+    // keep trace id and helm from memo if present (child workflow)
+    const traceId = memo.traceId ?? workflowId;
+    const traceHelm = memo.traceHelm ?? name;
 
-      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+    Object.assign( memo, { traceId, traceHelm } );
 
-      sinks.log.trace( { event: TraceEvent.WORKFLOW_END, output } );
+    // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
+    const output = await fn.call( {
+      invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+      invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
 
-      // add trace if not child
-      if ( !memo.rootWorkflowId ) {
-        const trace = await steps[READ_TRACE_FILE]( { workflowType: name, workflowId } );
-        return { output, trace };
+      startWorkflow: async ( childName, input ) => {
+        return executeChild( childName, { args: input ? [ input ] : [], memo: { traceId, traceHelm, parentId: workflowId } } );
       }
+    }, input );
 
-      return output;
-    } catch ( error ) {
-      /*
-       * Any errors in the workflow will interrupt its execution since the workflow is designed to orchestrate and
-       * IOs should be made in steps
-       */
-      throw new ApplicationFailure( error.message, error.constructor.name );
+    validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+
+    // Adds trace file content to the output if it is the root workflow
+    // @TODO this will be replaced in favor of a persistent storage elsewhere
+    if ( !memo.parentId ) {
+      const trace = await steps[ACTIVITY_READ_TRACE_FILE]( { traceId, traceHelm } );
+      return { output, trace };
     }
+
+    return output;
   };
 
   setMetadata( wrapper, { name, description, inputSchema, outputSchema } );

package/src/internal_activities/index.js

@@ -1,6 +1,8 @@
 import { FatalError } from '#errors';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { setMetadata } from '../interface/metadata.js';
+import { ComponentType } from '#consts';
 
 const callerDir = process.argv[2];
 
@@ -13,7 +15,7 @@ const callerDir = process.argv[2];
  * @param {any} options.payload - The payload to send url
  * @throws {FatalError}
  */
-export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
+export const sendWebhook = async ( { url, workflowId, payload } ) => {
   const request = fetch( url, {
     method: 'POST',
     headers: {
@@ -31,37 +33,39 @@ export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
     }
   } )();
 
-  console.log( '[Core.SendWebhookPost]', res.status, res.statusText );
+  console.log( '[Core.SendWebhook]', res.status, res.statusText );
 
   if ( !res.ok ) {
     throw new FatalError( `Webhook fail: ${res.status}` );
   }
 };
 
+setMetadata( sendWebhook, { type: ComponentType.INTERNAL_STEP } );
+
 /**
  * Read the trace file of a given execution and returns the content
  *
  * @param {object} options
- * @param {string} options.workflowType - The type of the workflow
- * @param {string} options.workflowId - The workflow execution id
+ * @param {string} options.traceId - The is of the trace
+ * @param {string} options.traceHelm - The helm of the trace file
  * @returns {string[]} Each line of the trace file
  */
-export const readTraceFile = async ( { workflowType, workflowId } ) => {
-  const dir = join( callerDir, 'logs', 'runs', workflowType );
+export const readTraceFile = async ( { traceId, traceHelm } ) => {
+  const dir = join( callerDir, 'logs', 'runs', traceHelm );
 
   if ( !existsSync( dir ) ) {
     console.log( '[Core.ReadTraceFile]', 'Trace folder not found', dir );
     return [];
   }
 
-  const suffix = `-${workflowId}.raw`;
-  const matchingFile = readdirSync( dir ).find( f => f.endsWith( suffix ) );
+  const fileName = readdirSync( dir ).find( f => f.endsWith( `-${traceId}.raw` ) );
 
-  if ( !matchingFile ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace file not found', dir, suffix );
+  if ( !fileName ) {
+    console.log( '[Core.ReadTraceFile]', 'Trace file not found', { traceId, traceHelm } );
     return [];
   }
 
-  const file = join( dir, matchingFile );
-  return existsSync( file ) ? readFileSync( file, 'utf-8' ).split( '\n' ) : [];
+  return readFileSync( join( dir, fileName ), 'utf-8' ).split( '\n' );
 };
+
+setMetadata( readTraceFile, { type: ComponentType.INTERNAL_STEP, skipTrace: true } );

package/src/tracing/index.d.ts

@@ -0,0 +1,47 @@
+/*
+╭───────────╮
+│ T R A C E │╮
+╰───────────╯│
+ ╰───────────╯
+*/
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export declare const Tracing: {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart( args: { id: string; kind: string; name: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+};

package/src/tracing/index.js

@@ -0,0 +1,154 @@
+import { Storage } from '#async_storage';
+import { mkdirSync, existsSync, readdirSync, appendFileSync } from 'node:fs';
+import { join } from 'path';
+import { EOL } from 'os';
+import { buildLogTree } from './tracer_tree.js';
+import { serializeError } from './utils.js';
+
+const callerDir = process.argv[2];
+// It is is isolated here instead of #configs to allow this module to be exported without all other configs requirements
+const tracingEnabled = [ '1', 'true', 'on' ].includes( process.env.TRACING_ENABLED );
+
+/**
+ * Trace nomenclature
+ *
+ * Trace - The collection of Events;
+ * Event - Any entry in the Trace file, must have the two phases START and END or ERROR;
+ * Phase - An specific part of an Event, either START or the conclusive END or ERROR;
+ */
+
+/**
+ * Adds the Trace Event Phase to the trace file
+ *
+ * @param {string} phase - The phase
+ * @param {object} options - All the trace fields
+ * @returns {void}
+ */
+function addEventPhase( phase, { kind, details, id, name, parentId, traceId, traceHelm } ) {
+  if ( !tracingEnabled || name === 'catalog' ) {
+    return;
+  }
+
+  const parsedDetails = details instanceof Error ? serializeError( details ) : details;
+  const timestamp = Date.now();
+  const entry = { phase, kind, details: parsedDetails, id, name, timestamp, parentId };
+  const outputDir = join( callerDir, 'logs', 'runs', traceHelm );
+
+  if ( !existsSync( outputDir ) ) {
+    mkdirSync( outputDir, { recursive: true } );
+  }
+
+  const suffix = `-${traceId}.raw`;
+  const logFile = readdirSync( outputDir ).find( f => f.endsWith( suffix ) ) ?? `${new Date( timestamp ).toISOString()}-${suffix}`;
+  const logPath = join( outputDir, logFile );
+
+  appendFileSync( logPath, JSON.stringify( entry ) + EOL, 'utf-8' );
+  buildLogTree( logPath );
+};
+
+/**
+ * Internal use only
+ *
+ * Adds the start phase of a new event at the default trace for the current workflow.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventStart = options => addEventPhase( 'start', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the end phase at an event at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventEnd = options => addEventPhase( 'end', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the error phase at an event as error at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventError = options => addEventPhase( 'error', options );
+
+/**
+ * Adds an Event Phase reading traceId, traceHelm and parentId from the context.
+ *
+ * @param {object} options - The common trace configurations
+ */
+function addEventPhaseWithContext( phase, options ) {
+  const storeContent = Storage.load();
+  if ( !storeContent ) { // means this was called from a unit test
+    return;
+  }
+  const { parentId, traceId, traceHelm } = storeContent;
+  addEventPhase( phase, { ...options, parentId, traceId, traceHelm } );
+};
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export const Tracing = {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart: ( { id, kind, name, details } ) => addEventPhaseWithContext( 'start', { kind, name, details, id } ),
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd: ( { id, details } ) => addEventPhaseWithContext( 'end', { id, details } ),
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError: ( { id, details } ) => addEventPhaseWithContext( 'error', { id, details } )
+};

package/src/tracing/index.private.spec.js

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir, EOL } from 'node:os';
+import { join } from 'path';
+
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'output-sdk-trace-' ) );
+
+// Use env var to enable tracing
+
+vi.mock( '#async_storage', () => ( { Storage: { load: () => ( { parentId: undefined, traceId: 'trace-1', traceHelm: 'tests' } ) } } ) );
+vi.mock( 'path', async importActual => {
+  const actual = await importActual();
+  return { ...actual, join: ( first, ...rest ) => actual.join( first ?? process.cwd(), ...rest ) };
+} );
+vi.mock( './tracer_tree.js', () => ( { buildLogTree: vi.fn() } ) );
+
+describe( 'tracing private exports', () => {
+  beforeEach( () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime( new Date( '2020-01-01T00:00:00.000Z' ) );
+    process.env.TRACING_ENABLED = '1';
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+    delete process.env.TRACING_ENABLED;
+  } );
+
+  it( 'addEventStart (private) writes start', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventStart } = await import( './index.js?v=private1' );
+    addEventStart( { id: 'a', kind: 'evaluator', name: 'start', details: { foo: 1 }, traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'start' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventEnd (private) writes end', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventEnd } = await import( './index.js?v=private2' );
+    addEventEnd( { id: 'a', details: { ok: true }, traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'end' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventError (private) writes error', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventError } = await import( './index.js?v=private3' );
+    addEventError( { id: 'a', details: new Error( 'oops' ), traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'error' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+} );

package/src/tracing/index.public.spec.js

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir, EOL } from 'node:os';
+import { join } from 'path';
+
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'output-sdk-trace-' ) );
+
+// Async storage mock to drive parent ids
+
+const mockStorageData = { parentId: undefined, traceId: 'trace-1', traceHelm: 'tests' };
+vi.mock( '#async_storage', () => ( { Storage: { load: () => mockStorageData } } ) );
+
+vi.mock( './tracer_tree.js', () => ( { buildLogTree: vi.fn() } ) );
+
+describe( 'Tracing (public namespace)', () => {
+  beforeEach( () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime( new Date( '2020-01-01T00:00:00.000Z' ) );
+    process.env.TRACING_ENABLED = '1';
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+    delete process.env.TRACING_ENABLED;
+  } );
+
+  it( 'addEventStart writes a start entry', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { Tracing } = await import( './index.js' );
+    Tracing.addEventStart( { id: '1', kind: 'evaluator', name: 'start', details: { a: 1 } } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const firstLine = raw.split( EOL )[0];
+    const entry = JSON.parse( firstLine );
+    expect( entry ).toMatchObject( { phase: 'start', kind: 'evaluator', name: 'start', id: '1', details: { a: 1 } } );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventEnd writes an end entry', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { Tracing } = await import( './index.js' );
+    Tracing.addEventEnd( { id: '1', details: { ok: true } } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const firstLine = raw.split( EOL )[0];
+    const entry = JSON.parse( firstLine );
+    expect( entry ).toMatchObject( { phase: 'end', id: '1', details: { ok: true } } );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventError writes an error entry', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { Tracing } = await import( './index.js' );
+    const error = new Error( 'boom' );
+    Tracing.addEventError( { id: '1', details: error } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const firstLine = raw.split( EOL )[0];
+    const entry = JSON.parse( firstLine );
+    expect( entry.phase ).toBe( 'error' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+} );