@archmax-ai/harness 2.1.0 → 2.2.0

package/dist/core/telemetry.d.ts

@@ -0,0 +1,213 @@
+/**
+ * OpenTelemetry for the runtime: one span per turn, per visit to a state, per
+ * model call and per tool call, and the GenAI client metrics for every model
+ * call — reported through `@opentelemetry/api` alone (a peer dependency), so a
+ * host sees them in its own trace once it registers an SDK, and nothing at all
+ * happens when it registers none.
+ *
+ * This module owns every span name, attribute name and recorded value, which
+ * is how the metadata-only rule holds: it takes slugs, model ids, counts and
+ * outcomes, never a message, an argument, a result or an error's message, and
+ * it records no exception.
+ *
+ * Turn, model-call and tool-call spans are made at their call sites and are
+ * active while the call runs, so whatever the call causes — the provider's HTTP
+ * request, a host tool's own spans, a sub-workflow's child turn — nests under
+ * it. A state visit is not one call: the sites that move a session report it on
+ * the event stream, which {@link Telemetry.observe} follows, and its children
+ * are parented to it explicitly ({@link Telemetry.parentFor}).
+ */
+import { type Context } from "@opentelemetry/api";
+import { type WorkflowLifecycleEvent } from "./events.js";
+import { type PricingTable } from "./usage.js";
+/** The instrumentation scope every span and metric is reported under. */
+export declare const TELEMETRY_SCOPE = "@archmax-ai/harness";
+/** Every attribute the runtime records, by the name the backend reads. */
+export declare const TELEMETRY_ATTRIBUTES: {
+    readonly operation: "gen_ai.operation.name";
+    readonly agentName: "gen_ai.agent.name";
+    readonly conversationId: "gen_ai.conversation.id";
+    readonly provider: "gen_ai.provider.name";
+    readonly requestModel: "gen_ai.request.model";
+    readonly responseModel: "gen_ai.response.model";
+    readonly finishReasons: "gen_ai.response.finish_reasons";
+    readonly inputTokens: "gen_ai.usage.input_tokens";
+    readonly outputTokens: "gen_ai.usage.output_tokens";
+    readonly cacheReadTokens: "gen_ai.usage.cache_read.input_tokens";
+    readonly cacheCreationTokens: "gen_ai.usage.cache_creation.input_tokens";
+    readonly cost: "gen_ai.usage.cost";
+    readonly toolName: "gen_ai.tool.name";
+    readonly toolCallId: "gen_ai.tool.call.id";
+    readonly toolType: "gen_ai.tool.type";
+    readonly tokenType: "gen_ai.token.type";
+    readonly errorType: "error.type";
+    readonly state: "archmax.state";
+    readonly stateType: "archmax.state.type";
+    readonly stateNext: "archmax.state.next";
+    readonly stateResumed: "archmax.state.resumed";
+    readonly stateParked: "archmax.state.parked";
+    readonly raiseCode: "archmax.raise.code";
+    readonly turnResume: "archmax.turn.resume";
+    readonly sessionStatus: "archmax.session.status";
+    readonly dispatchId: "archmax.dispatch.id";
+    readonly modelRole: "archmax.model.role";
+    readonly responseToolCalls: "archmax.response.tool_calls";
+    readonly toolOrigin: "archmax.tool.origin";
+    readonly toolOutcome: "archmax.tool.outcome";
+    readonly toolRule: "archmax.tool.rule";
+};
+/** The two GenAI client metrics, by name. */
+export declare const TELEMETRY_METRICS: {
+    readonly operationDuration: "gen_ai.client.operation.duration";
+    readonly tokenUsage: "gen_ai.client.token.usage";
+};
+/**
+ * A tool's name as a span reports it: the name when it is a plain tool
+ * identifier, else `unknown` — a model can call a tool by any string at all.
+ */
+export declare function reportedToolName(name: string): string;
+/** A raise's code when it is a short token, else nothing: the raiser chose it. */
+export declare function reportedRaiseCode(code: unknown): string | undefined;
+/** A model id when it reads as one, else nothing. */
+export declare function reportedModelId(id: unknown): string | undefined;
+/** A tool call's id as a span reports it, when it reads as an id. */
+export declare function reportedCallId(id: unknown): string | undefined;
+/**
+ * An error's `error.type`: the HTTP status it carries (`429`), else its class
+ * name (`AbortError`, from its `name` or its constructor's), else `Error`.
+ * Never its message, which can quote what the call was given, and never a
+ * `name` that is not shaped like a class name.
+ */
+export declare function errorTypeOf(err: unknown): string;
+/** The `gen_ai.provider.name` of a chat model, from LangChain's own model type. */
+export declare function providerOf(model: unknown): string | undefined;
+/** What starts a turn's span. */
+export interface TurnStart {
+    sessionId: string;
+    /** The workflow slug; absent for a plain agent. */
+    workflow?: string;
+    /** The turn resumes a park (a decision, a reply, a delivery). */
+    resume?: boolean;
+    /** A state's type, for the state spans of a governed turn. */
+    stateType?: (slug: string) => string | undefined;
+}
+/** How a turn settled, read from what it returned. */
+export interface TurnSettled {
+    /** The session's status after the turn. */
+    status?: string;
+    /** The state the turn ended in. */
+    state?: string;
+}
+/** A turn in flight: the context its work runs in, and how it ends. */
+export interface TurnHandle {
+    context: Context;
+    /** Whether a provider is recording it: what spares a no-op turn any extra work. */
+    recording: boolean;
+    end(settled?: TurnSettled): void;
+    fail(err: unknown): void;
+}
+/** A model call in flight. */
+export interface ModelCallHandle {
+    /** The context the call runs in: its span active. */
+    context: Context;
+    /** The call answered: its usage, the model it named, its finish. Ends the span. */
+    settle(response: unknown): void;
+    /** The call threw. Ends the span. */
+    fail(err: unknown): void;
+    /** The call outlived its time budget. Ends the span; a late answer changes nothing. */
+    expire(): void;
+}
+/** How a tool call ended. */
+export type ToolOutcome = "ok" | "error" | "blocked" | "unknown" | "parked" | "cancelled";
+/** Who made a tool call. */
+export type ToolOrigin = "agent" | "grader" | "script";
+/** A tool call in flight. */
+export interface ToolCallHandle {
+    /** The context the call runs in: its span active, marked as a tool call of its session. */
+    context: Context;
+    /** The tool the call reached, once its name is resolved. */
+    rename(tool: string): void;
+    /** How it ended, and — when blocked — the rule that blocked it. Ends the span. */
+    end(outcome: ToolOutcome, rule?: string): void;
+}
+/** What a model call's span is opened with. */
+export interface ModelCallStart {
+    sessionId: string;
+    /** The state the call is made in; absent for a plain agent. */
+    state?: string;
+    role: "agent" | "grader";
+    /** The chat model the call runs on. */
+    model: unknown;
+    /** The id the call asks the endpoint for. */
+    requestModel?: string;
+    /** Prices, and the id a call whose response names none is priced as — what its `model-usage` event uses. */
+    pricing?: PricingTable;
+    pricingModel?: string;
+}
+/** What a tool call's span is opened with. */
+export interface ToolCallStart {
+    sessionId: string;
+    state?: string;
+    /** The name the call was made with. */
+    tool: string;
+    /** The call's id, as its events carry it. */
+    callId: string;
+    origin: ToolOrigin;
+}
+/**
+ * The runtime's telemetry for one assembly: the spans of every turn its
+ * compositions run, a sub-workflow's children included, keyed by session.
+ */
+export declare class Telemetry {
+    #private;
+    /**
+     * Open a turn's span in the active context. Call {@link TurnHandle.end} or
+     * {@link TurnHandle.fail} exactly once.
+     */
+    openTurn(start: TurnStart): TurnHandle;
+    /**
+     * Run `fn` as one turn: its span active throughout, settled from what `fn`
+     * returned, failed by what it threw (which still propagates).
+     */
+    turn<T>(start: TurnStart, fn: () => Promise<T>, settled: (result: T) => TurnSettled): Promise<T>;
+    /**
+     * Follow the event stream: a state entered opens its span, a state left ends
+     * it, and a park, a failed automated run, an `on_error` route and a raise
+     * mark it. Events of a session with no open turn are ignored.
+     */
+    observe(event: WorkflowLifecycleEvent): void;
+    /**
+     * The context a model or tool call's span is opened in: the active one when
+     * it is inside a tool call of the same session (a script's call); else the
+     * active one with its span replaced by the turn's — the open span of the state
+     * the call is made in; else, when the turn has opened no state yet (it
+     * continues in the state the session was in), that state's span, opened now
+     * and marked resumed; else the turn's own span (a call of a batch made in a
+     * state the batch has already left). A session with no open turn leaves the
+     * active context as it is.
+     */
+    parentFor(sessionId: string, state?: string): Context;
+    /** Open a model call's span under {@link parentFor}. */
+    modelCall(start: ModelCallStart): ModelCallHandle;
+    /** Open a tool call's span under {@link parentFor}, marked as a tool call of its session. */
+    toolCall(start: ToolCallStart): ToolCallHandle;
+}
+/** Whether a tool's answer is the runtime's refusal of the call. */
+export declare function isBlockedAnswer(answer: unknown): boolean;
+/** Whether a tool's answer is an error the model reads. */
+export declare function isErrorAnswer(answer: unknown): boolean;
+/**
+ * The outcome of a tool call that threw `err`: a park (the session's own, or a
+ * sub-workflow's carried up through the call) is not the call's failure, a
+ * command to the parent graph is how the call answered, and a throw after the
+ * turn was cancelled is the cancellation's.
+ */
+export declare function thrownOutcomeOf(err: unknown, signal: AbortSignal | undefined): ToolOutcome;
+/** The outcome of a tool call that settled with `answer`. */
+export declare function toolOutcomeOf(answer: unknown): ToolOutcome;
+/**
+ * Whether a tool's answer parks the session: it commits a pending input
+ * (`archmax_wait` accepted), a pending decision, or a pending delegation (a
+ * sub-workflow that stopped for a person).
+ */
+export declare function isParkingAnswer(answer: unknown): boolean;