@fifthrevision/axle 0.18.0 → 0.20.0

package/dist/accumulator-D2NgIGxp.d.ts

@@ -0,0 +1,547 @@
+//#region src/types.d.ts
+/**
+ * Token usage reported by a provider response.
+ */
+interface Stats {
+  /** Total effective input tokens. Includes `cachedIn` and `cacheWriteIn` when reported. */
+  in: number;
+  /** Total output tokens. Includes `reasoningOut` when reported. */
+  out: number;
+  /** Input tokens served from provider prompt/context cache. Included in `in`. */
+  cachedIn?: number;
+  /** Input tokens written into provider prompt/context cache. Included in `in`. */
+  cacheWriteIn?: number;
+  /** Output tokens spent on reasoning/thinking. Included in `out`. */
+  reasoningOut?: number;
+}
+//#endregion
+//#region src/tracer/types.d.ts
+type SpanStatus = "ok" | "error";
+type EventLevel = "debug" | "info" | "warn" | "error";
+type SpanType = string;
+interface SpanEvent {
+  name: string;
+  timestamp: number;
+  level: EventLevel;
+  attributes?: Record<string, unknown>;
+}
+interface SpanData {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  type?: SpanType;
+  startTime: number;
+  endTime?: number;
+  status: SpanStatus;
+  attributes: Record<string, unknown>;
+  events: SpanEvent[];
+  result?: SpanResult;
+}
+interface SpanOptions {
+  type?: SpanType;
+}
+type SpanResult = LLMResult | ToolResult;
+interface LLMResult {
+  kind: "llm";
+  model: string;
+  request: LLMRequest;
+  response: LLMResponse;
+  usage?: TokenUsage;
+  finishReason?: string;
+}
+interface LLMRequest {
+  messages: unknown[];
+  system?: string;
+  tools?: unknown[];
+}
+interface LLMResponse {
+  content: unknown;
+}
+interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  cachedInputTokens?: number;
+  cacheWriteInputTokens?: number;
+  reasoningOutputTokens?: number;
+}
+interface ToolResult {
+  kind: "tool";
+  name: string;
+  input: unknown;
+  output: unknown;
+}
+interface TraceWriter {
+  onSpanStart(span: SpanData): void;
+  onSpanUpdate?(span: SpanData): void;
+  onSpanEnd(span: SpanData): void;
+  onEvent?(span: SpanData, event: SpanEvent): void;
+  flush?(): Promise<void>;
+}
+/**
+ * Tracing context for a span. Created by Tracer.startSpan().
+ * Can create child spans and log events within the span's scope.
+ */
+interface TracingContext {
+  startSpan(name: string, options?: SpanOptions): TracingContext;
+  end(status?: SpanStatus): void;
+  debug(message: string, attributes?: Record<string, unknown>): void;
+  info(message: string, attributes?: Record<string, unknown>): void;
+  warn(message: string, attributes?: Record<string, unknown>): void;
+  error(message: string, attributes?: Record<string, unknown>): void;
+  setAttribute(key: string, value: unknown): void;
+  setAttributes(attributes: Record<string, unknown>): void;
+  setResult(result: SpanResult): void;
+}
+//#endregion
+//#region src/utils/file.d.ts
+type FileKind = "image" | "document" | "text";
+type TextSource = {
+  type: "text";
+  content: string;
+} | {
+  type: "url";
+  url: string;
+} | {
+  type: "ref";
+  ref: unknown;
+};
+type BinarySource = {
+  type: "base64";
+  data: string;
+} | {
+  type: "url";
+  url: string;
+} | {
+  type: "ref";
+  ref: unknown;
+};
+interface BaseFile {
+  mimeType: string;
+  name: string;
+  size?: number;
+}
+type TextFileInfo = BaseFile & {
+  kind: "text";
+  source: TextSource;
+};
+type BinaryFileInfo = BaseFile & {
+  kind: "image" | "document";
+  source: BinarySource;
+};
+type FileInfo = TextFileInfo | BinaryFileInfo;
+type InlineTextFile = TextFileInfo & {
+  source: {
+    type: "text";
+    content: string;
+  };
+};
+type InlineBinaryFile = BinaryFileInfo & {
+  source: {
+    type: "base64";
+    data: string;
+  };
+};
+type DeferredFileInfo = FileInfo & {
+  source: {
+    type: "ref";
+    ref: unknown;
+  };
+};
+type ConcreteFileInfo = FileInfo & {
+  source: {
+    type: "text";
+  } | {
+    type: "base64";
+  } | {
+    type: "url";
+  };
+};
+type FileProviderId = "anthropic" | "openai" | "gemini" | "chatcompletions";
+type FileResolveFormat = "base64" | "url" | "text" | "gemini-file-uri";
+type ResolvedFileSource = {
+  type: "base64";
+  data: string;
+  mimeType?: string;
+  name?: string;
+} | {
+  type: "url";
+  url: string;
+  mimeType?: string;
+  name?: string;
+} | {
+  type: "text";
+  content: string;
+  mimeType?: string;
+  name?: string;
+} | {
+  type: "gemini-file-uri";
+  uri: string;
+  mimeType?: string;
+  name?: string;
+};
+interface FileResolveRequest {
+  file: DeferredFileInfo;
+  ref: unknown;
+  provider: FileProviderId;
+  model: string;
+  accepted: FileResolveFormat[];
+  signal?: AbortSignal;
+}
+type FileResolver = (request: FileResolveRequest) => Promise<ResolvedFileSource>;
+/**
+ * Load a file with the specified encoding or auto-detect based on file extension
+ * @param filePath - Path to the file
+ * @param encoding - How to load the file: "utf-8" for text, "base64" for binary, or omit for auto-detection
+ * @returns FileInfo object with appropriate content based on encoding
+ */
+declare function loadFileContent(filePath: string): Promise<FileInfo>;
+declare function loadFileContent(filePath: string, encoding: "utf-8"): Promise<InlineTextFile>;
+declare function loadFileContent(filePath: string, encoding: "base64"): Promise<InlineBinaryFile>;
+//#endregion
+//#region src/turns/types.d.ts
+/**
+ * Lifecycle state for a renderable turn.
+ *
+ * Turns are presentation state. They describe what a consumer can render, not
+ * the canonical model conversation state.
+ */
+type TurnStatus = "streaming" | "complete" | "cancelled" | "error";
+/**
+ * ISO timestamp metadata for a turn, part, action, or annotation.
+ */
+interface TimingInfo {
+  /** ISO timestamp for when the item started. */
+  start: string;
+  /** ISO timestamp for when the item finished, when known. */
+  end?: string;
+}
+/**
+ * Where an annotation should render relative to its target.
+ */
+type AnnotationPlacement = "before" | "after";
+/**
+ * Lifecycle state for an annotation.
+ *
+ * Omit this for static/informational annotations that do not have a running or
+ * terminal state.
+ */
+type AnnotationStatus = "running" | "complete" | "cancelled" | "error";
+/**
+ * Render metadata attached to a session, turn, or turn part.
+ *
+ * Annotations let hosts attach out-of-band UI such as sandbox startup, eval
+ * results, or deployment state without turning that data into model state.
+ *
+ * @typeParam TData - Consumer-owned payload for the annotation kind.
+ * @typeParam TKind - Discriminator for the annotation kind.
+ */
+interface Annotation<TData = unknown, TKind extends string = string> {
+  /** Globally unique annotation id. */
+  id: string;
+  /** Consumer-defined annotation kind, used as a discriminator. */
+  kind: TKind;
+  /** Human-readable label for generic renderers. */
+  label: string;
+  /** Render placement relative to the target. Defaults to `"after"` when accumulated. */
+  placement?: AnnotationPlacement;
+  /** Optional lifecycle state for the annotation. */
+  status?: AnnotationStatus;
+  /** Consumer-owned annotation payload. */
+  data?: TData;
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Renderable presentation state for one user or agent turn.
+ *
+ * `Turn` is the snapshot counterpart to `TurnEvent`: events describe changes,
+ * and turns are the accumulated render state. The model-facing conversation
+ * remains `AxleMessage[]`.
+ *
+ * @typeParam TAnnotation - Annotation union supported by the host renderer.
+ */
+interface Turn<TAnnotation extends Annotation = Annotation> {
+  /** Stable turn id. */
+  id: string;
+  /** Whether the turn was produced by the user or the agent. */
+  owner: "user" | "agent";
+  /** Renderable parts in display order. */
+  parts: TurnPart<TAnnotation>[];
+  /** Current lifecycle state for the turn. */
+  status: TurnStatus;
+  /** Annotations attached to the whole turn. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+  /** Token usage accumulated for this turn, when available. */
+  usage?: Stats;
+}
+/**
+ * Any renderable part within a turn.
+ */
+type TurnPart<TAnnotation extends Annotation = Annotation> = TextPart<TAnnotation> | FilePart<TAnnotation> | ThinkingPart<TAnnotation> | ActionPart<TAnnotation>;
+/**
+ * Assistant or user text content.
+ */
+interface TextPart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "text";
+  /** Accumulated text content. */
+  text: string;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * File content attached to a user turn.
+ */
+interface FilePart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "file";
+  /** File metadata and source reference. */
+  file: FileInfo;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Model thinking or reasoning content when surfaced by the provider.
+ */
+interface ThinkingPart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. */
+  id: string;
+  /** Part discriminator. */
+  type: "thinking";
+  /** Accumulated thinking text. */
+  text: string;
+  /** Optional provider-supplied summary. */
+  summary?: string;
+  /** Whether the provider marked the thinking content as redacted. */
+  redacted?: boolean;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
+/**
+ * Shared fields for tool, subagent, and provider-managed actions.
+ *
+ * @internal
+ */
+interface ActionPartBase<TAnnotation extends Annotation = Annotation> {
+  id: string;
+  type: "action";
+  kind: string;
+  status: "pending" | "running" | "complete" | "cancelled" | "error";
+  annotations?: TAnnotation[];
+  timing?: TimingInfo;
+}
+/**
+ * Action part for an executable Axle tool call.
+ */
+interface ToolAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "tool";
+  /** Tool display and execution details. */
+  detail: {
+    /** Tool name. */name: string; /** Parsed tool parameters once execution starts. */
+    parameters: Record<string, unknown>; /** Accumulated JSON argument text before parameters are parsed. */
+    pendingArgs?: string; /** Tool result or in-progress output. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Action part for a nested agent/subagent run.
+ */
+interface SubagentAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "agent";
+  /** Subagent display and result details. */
+  detail: {
+    /** Subagent name. */name: string; /** Optional subagent configuration shown to renderers. */
+    config?: Record<string, unknown>; /** Child turns produced by the subagent. */
+    children: Turn<TAnnotation>[]; /** Final subagent result, when available. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Action part for provider-managed tools such as hosted web search or code
+ * execution.
+ */
+interface ProviderToolAction<TAnnotation extends Annotation = Annotation> extends ActionPartBase<TAnnotation> {
+  /** Action discriminator. */
+  kind: "provider-tool";
+  /** Provider tool display and result details. */
+  detail: {
+    /** Provider tool name. */name: string; /** Provider-specific input, when surfaced. */
+    input?: unknown; /** Provider tool result, when surfaced. */
+    result?: ActionResult;
+  };
+}
+/**
+ * Any action part in a turn.
+ */
+type ActionPart<TAnnotation extends Annotation = Annotation> = ToolAction<TAnnotation> | SubagentAction<TAnnotation> | ProviderToolAction<TAnnotation>;
+/**
+ * Renderable result for an action.
+ */
+type ActionResult = {
+  type: "in-progress";
+  content: string;
+} | {
+  type: "success";
+  content: unknown;
+} | {
+  type: "error";
+  error: {
+    type: string;
+    message: string;
+  };
+};
+//#endregion
+//#region src/turns/events.d.ts
+type AnnotationTarget = {
+  type: "session";
+} | {
+  type: "turn";
+  turnId: string;
+} | {
+  type: "part";
+  turnId: string;
+  partId: string;
+};
+type AnnotationEvent<TAnnotation extends Annotation = Annotation> = {
+  type: "annotation:start";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+} | {
+  type: "annotation:update";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+} | {
+  type: "annotation:end";
+  target: AnnotationTarget;
+  annotation: TAnnotation;
+};
+type TurnEvent<TAnnotation extends Annotation = Annotation> = {
+  type: "session:restore";
+  turns: Turn<TAnnotation>[];
+  sessionAnnotations?: TAnnotation[];
+  config?: Record<string, unknown>;
+} | {
+  type: "turn:user";
+  turn: Turn<TAnnotation>;
+} | {
+  type: "turn:start";
+  turnId: string;
+  timing?: TimingInfo;
+} | {
+  type: "turn:end";
+  turnId: string;
+  status: TurnStatus;
+  usage: Stats;
+  timing?: TimingInfo;
+} | {
+  type: "part:start";
+  turnId: string;
+  part: TurnPart<TAnnotation>;
+} | {
+  type: "text:delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+} | {
+  type: "thinking:delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+} | {
+  type: "part:end";
+  turnId: string;
+  partId: string;
+  timing?: TimingInfo;
+} | {
+  type: "action:args-delta";
+  turnId: string;
+  partId: string;
+  delta: string;
+  accumulated: string;
+} | {
+  type: "action:running";
+  turnId: string;
+  partId: string;
+  parameters?: Record<string, unknown>;
+} | {
+  type: "action:progress";
+  turnId: string;
+  partId: string;
+  chunk: string;
+} | {
+  type: "action:complete";
+  turnId: string;
+  partId: string;
+  result: ActionResult;
+  timing?: TimingInfo;
+} | {
+  type: "action:error";
+  turnId: string;
+  partId: string;
+  error: {
+    type: string;
+    message: string;
+  };
+  timing?: TimingInfo;
+} | {
+  type: "action:child-event";
+  turnId: string;
+  partId: string;
+  event: TurnEvent<TAnnotation>;
+} | AnnotationEvent<TAnnotation> | {
+  type: "error";
+  error: {
+    type: string;
+    message: string;
+  };
+};
+//#endregion
+//#region src/turns/accumulator.d.ts
+interface TurnAccumulatorState<TAnnotation extends Annotation = Annotation> {
+  turns: Turn<TAnnotation>[];
+  sessionAnnotations?: TAnnotation[];
+}
+type UnknownEvent = {
+  type: string;
+};
+type AccumulatableEvent<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> = TurnEvent<TAnnotation> | THostEvent;
+type TurnAccumulatorResult<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> = {
+  handled: true;
+  state: TurnAccumulatorState<TAnnotation>;
+  event: TurnEvent<TAnnotation>;
+} | {
+  handled: false;
+  state: TurnAccumulatorState<TAnnotation>;
+  event: THostEvent;
+};
+declare class TurnAccumulator<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> {
+  private _state;
+  constructor(init?: TurnAccumulatorState<TAnnotation>);
+  get state(): TurnAccumulatorState<TAnnotation>;
+  apply(event: AccumulatableEvent<TAnnotation, THostEvent>): TurnAccumulatorResult<TAnnotation, THostEvent>;
+  private replaceState;
+  private replaceTurns;
+  private updateTurn;
+  private updatePart;
+  private addAnnotation;
+  private replaceAnnotation;
+  private handled;
+}
+//#endregion
+export { FileResolveRequest as A, TracingContext as B, TurnStatus as C, FileKind as D, FileInfo as E, SpanData as F, SpanEvent as I, SpanOptions as L, ResolvedFileSource as M, loadFileContent as N, FileProviderId as O, EventLevel as P, SpanType as R, TurnPart as S, DeferredFileInfo as T, Stats as V, TextPart as _, UnknownEvent as a, ToolAction as b, TurnEvent as c, Annotation as d, AnnotationPlacement as f, SubagentAction as g, ProviderToolAction as h, TurnAccumulatorState as i, FileResolver as j, FileResolveFormat as k, ActionPart as l, FilePart as m, TurnAccumulator as n, AnnotationEvent as o, AnnotationStatus as p, TurnAccumulatorResult as r, AnnotationTarget as s, AccumulatableEvent as t, ActionResult as u, ThinkingPart as v, ConcreteFileInfo as w, Turn as x, TimingInfo as y, TraceWriter as z };

package/dist/accumulator-vmmD3pxt.js

@@ -0,0 +1 @@
+var e=class{_state;constructor(e){this._state={turns:e?.turns??[],sessionAnnotations:e?.sessionAnnotations}}get state(){return this._state}apply(e){let t=e;switch(e.type){case`session:restore`:return this.replaceState({turns:t.turns??[],sessionAnnotations:t.sessionAnnotations},e);case`turn:user`:return this.replaceTurns([...this._state.turns,t.turn],e);case`turn:start`:{let n={id:t.turnId,owner:`agent`,parts:[],status:`streaming`,...t.timing?{timing:t.timing}:{}};return this.replaceTurns([...this._state.turns,n],e)}case`part:start`:return this.updateTurn(t.turnId,e,e=>({...e,parts:[...e.parts,t.part]}));case`text:delta`:return this.updatePart(t.turnId,t.partId,e,e=>e.type===`text`?{...e,text:e.text+t.delta}:e);case`thinking:delta`:return this.updatePart(t.turnId,t.partId,e,e=>e.type===`thinking`?{...e,text:e.text+t.delta}:e);case`part:end`:return this.updatePart(t.turnId,t.partId,e,e=>({...e,timing:t.timing??e.timing}));case`action:args-delta`:return this.updatePart(t.turnId,t.partId,e,e=>e.type!==`action`||e.kind!==`tool`?e:{...e,detail:{...e.detail,pendingArgs:t.accumulated}});case`action:running`:return this.updatePart(t.turnId,t.partId,e,e=>{if(e.type!==`action`)return e;if(e.kind===`tool`){let{pendingArgs:n,...r}=e.detail;return{...e,status:`running`,detail:t.parameters?{...r,parameters:t.parameters}:r}}return{...e,status:`running`}});case`action:progress`:return this.updatePart(t.turnId,t.partId,e,e=>{if(e.type!==`action`)return e;let n=e.detail.result,r=n?.type===`in-progress`?n.content:``;return{...e,detail:{...e.detail,result:{type:`in-progress`,content:r+t.chunk}}}});case`action:complete`:return this.updatePart(t.turnId,t.partId,e,e=>e.type===`action`?{...e,status:`complete`,detail:{...e.detail,result:t.result},timing:t.timing??e.timing}:e);case`action:error`:return this.updatePart(t.turnId,t.partId,e,e=>e.type===`action`?{...e,status:`error`,detail:{...e.detail,result:{type:`error`,error:t.error}},timing:t.timing??e.timing}:e);case`turn:end`:return this.updateTurn(t.turnId,e,e=>({...e,status:t.status,usage:t.usage,timing:t.timing??e.timing}));case`annotation:start`:return this.addAnnotation(e);case`annotation:update`:return this.replaceAnnotation(e,!1);case`annotation:end`:return this.replaceAnnotation(e,!0);case`error`:case`action:child-event`:return this.handled(e);default:return{handled:!1,state:this._state,event:e}}}replaceState(e,t){return this._state=e,this.handled(t)}replaceTurns(e,t){return this.replaceState({...this._state,turns:e},t)}updateTurn(e,t,n){let r=!1,i=this._state.turns.map(t=>{if(t.id!==e)return t;let i=n(t);return i===t?t:(r=!0,i)});return r?this.replaceTurns(i,t):this.handled(t)}updatePart(e,t,n,r){return this.updateTurn(e,n,e=>{let n=!1,i=e.parts.map(e=>{if(e.id!==t)return e;let i=r(e);return i===e?e:(n=!0,i)});return n?{...e,parts:i}:e})}addAnnotation(e){let n=e,r=n.target,i=t(n.annotation);return!r||!i?this.handled(e):r.type===`session`?this.replaceState({...this._state,sessionAnnotations:[...this._state.sessionAnnotations??[],i]},e):r.type===`turn`?this.updateTurn(r.turnId,e,e=>({...e,annotations:[...e.annotations??[],i]})):r.type===`part`?this.updatePart(r.turnId,r.partId,e,e=>({...e,annotations:[...e.annotations??[],i]})):this.handled(e)}replaceAnnotation(e,r){let i=e,a=i.target,o=t(i.annotation,r);if(!a||!o)return this.handled(e);if(a.type===`session`){let t=n(this._state.sessionAnnotations,o);return t?this.replaceState({...this._state,sessionAnnotations:t},e):this.handled(e)}return a.type===`turn`?this.updateTurn(a.turnId,e,e=>{let t=n(e.annotations,o);return t?{...e,annotations:t}:e}):a.type===`part`?this.updatePart(a.turnId,a.partId,e,e=>{let t=n(e.annotations,o);return t?{...e,annotations:t}:e}):this.handled(e)}handled(e){return{handled:!0,state:this._state,event:e}}};function t(e,t=!1){if(!e)return;let n=t?e.status??`complete`:e.status,r={...e,placement:e.placement??`after`};return n?{...r,status:n}:r}function n(e,t){if(!e)return;let n=!1,r=e.map(e=>e.id===t.id?(n=!0,t):e);return n?r:void 0}export{e as t};