@tangle-network/agent-runtime 0.35.0 → 0.37.0

package/dist/otel-export-xgf4J6bo.d.ts

@@ -1,191 +0,0 @@
-import { O as OpenAIChatTool } from './types-CsCCryln.js';
-
-/**
- * @experimental
- *
- * OpenAI Chat Completions `tools[]` projection of the 5 agent-runtime MCP
- * delegation tools.
- *
- * Use when configuring `createOpenAICompatibleBackend({ tools: ... })` so the
- * model can call `delegate_code`, `delegate_research`, `delegate_feedback`,
- * `delegation_status`, and `delegation_history` through the OpenAI-compat
- * transport (tcloud, OpenRouter, OpenAI direct, cli-bridge). The runtime
- * surfaces tool calls as `tool_call` stream events — execution is the
- * caller's responsibility (typically the parent sandbox runtime's MCP
- * mount).
- *
- * Sandbox-SDK callers do NOT need this helper: the sandbox runtime mounts
- * MCP servers natively and the in-sandbox harness discovers tools via the
- * runtime, not via an OpenAI tools array.
- *
- * Tool name + description + JSON-schema are pulled from the canonical
- * `DELEGATE_*` constants exported by `./tools/*` so the projection cannot
- * drift from the server's own validators.
- */
-
-/**
- * @experimental
- *
- * Returns the 5 delegation tools projected into OpenAI Chat Completions
- * `tools[]` shape. The order is stable: `delegate_code`,
- * `delegate_research`, `delegate_feedback`, `delegation_status`,
- * `delegation_history`.
- */
-declare function mcpToolsForRuntimeMcp(): OpenAIChatTool[];
-/**
- * @experimental
- *
- * Subset filter — return only the projected tools whose `function.name`
- * appears in `names`. Useful for curated mounts (e.g. only the queue-bound
- * delegation tools, omitting `delegate_feedback`). Unknown names are
- * silently ignored; pass an empty array to get an empty result.
- */
-declare function mcpToolsForRuntimeMcpSubset(names: ReadonlyArray<string>): OpenAIChatTool[];
-
-/**
- * OTEL span exporter — streams LoopTraceEvents to an OTLP/HTTP collector.
- *
- * Reads OTEL_EXPORTER_OTLP_ENDPOINT + OTEL_EXPORTER_OTLP_HEADERS from env
- * when no explicit config is given. Keeps the runtime dep-free from
- * @opentelemetry/sdk-trace-base — minimal OTLP/JSON serializer.
- *
- * The exporter accepts both raw OtelSpan objects and LoopTraceEvents
- * (which get converted to OTLP spans automatically).
- */
-interface OtelExportConfig {
-    /** OTLP endpoint. Reads OTEL_EXPORTER_OTLP_ENDPOINT env by default. */
-    endpoint?: string;
-    /** OTLP headers. Reads OTEL_EXPORTER_OTLP_HEADERS env by default. */
-    headers?: Record<string, string>;
-    /** Batch size before flush. Default 64. */
-    batchSize?: number;
-    /** Flush interval ms. Default 5000. */
-    flushIntervalMs?: number;
-    /** Resource attributes stamped on every export. */
-    resourceAttributes?: Record<string, string | number | boolean>;
-    /** Service name. Default 'agent-runtime'. */
-    serviceName?: string;
-}
-interface OtelExporter {
-    /** Export a span. */
-    exportSpan(span: OtelSpan): void;
-    /** Force flush pending spans. */
-    flush(): Promise<void>;
-    /** Shutdown cleanly. */
-    shutdown(): Promise<void>;
-}
-interface OtelSpan {
-    traceId: string;
-    spanId: string;
-    parentSpanId?: string;
-    name: string;
-    kind?: number;
-    startTimeUnixNano: string;
-    endTimeUnixNano: string;
-    attributes?: OtelAttribute[];
-    status?: {
-        code: number;
-        message?: string;
-    };
-}
-interface OtelAttribute {
-    key: string;
-    value: {
-        stringValue?: string;
-        intValue?: string;
-        doubleValue?: number;
-        boolValue?: boolean;
-    };
-}
-/**
- * Create an OTEL exporter. Returns undefined when no endpoint is configured.
- */
-declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
-/**
- * Convert a LoopTraceEvent into an OtelSpan for export.
- */
-declare function loopEventToOtelSpan(event: {
-    kind: string;
-    runId: string;
-    timestamp: number;
-    payload: object;
-}, traceId: string, parentSpanId?: string): OtelSpan;
-/**
- * Build a nested, real-duration OTLP span tree for ONE loop run from its full
- * ordered `LoopTraceEvent` stream. Unlike `loopEventToOtelSpan` (one flat,
- * zero-duration span per event), this reconstructs the topology hierarchy a
- * GenAI trace viewer renders natively:
- *
- *   loop (invoke_workflow)
- *     └─ loop.round[k] (invoke_workflow)   ← tangle.loop.move.{kind,width,rationale}
- *          ├─ loop.iteration[i] (invoke_agent)  ← gen_ai.agent.name + usage + verdict + placement
- *          └─ …
- *
- * Attributes follow the current GenAI semconv (`gen_ai.*`) where they apply and
- * a namespaced `tangle.loop.*` / `tangle.cost.usd` extension for topology /
- * verdict / placement / cost (not yet standardized). Pure: feed it a buffered
- * per-runId event array (e.g. flushed on `loop.ended`) and export the result.
- */
-declare function buildLoopOtelSpans(events: ReadonlyArray<{
-    kind: string;
-    runId: string;
-    timestamp: number;
-    payload: object;
-}>, traceId: string, rootParentSpanId?: string): OtelSpan[];
-/** Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). */
-declare const INTELLIGENCE_WIRE_VERSION = "2026-05-26.v1";
-interface EvalRunGeneration {
-    /** 0-based ordinal of this generation within the run (required by ingest). */
-    index: number;
-    /** Identity of the proposed surface change (content-addressed hash). */
-    surfaceHash: string;
-    /** Arbitrary provenance for this generation (rationale, evidence, source). */
-    surface?: unknown;
-    /** Per-scenario results; empty until the generation is measured. */
-    cells?: unknown[];
-    /** Mean composite score (0 when unmeasured — pair with labels.measured). */
-    compositeMean: number;
-    costUsd: number;
-    durationMs: number;
-}
-interface EvalRunEvent {
-    runId: string;
-    runDir: string;
-    /** ISO timestamp. */
-    timestamp: string;
-    status: 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
-    labels?: Record<string, string>;
-    baseline?: EvalRunGeneration;
-    generations?: EvalRunGeneration[];
-    gateDecision?: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
-    holdoutLift?: number;
-    totalCostUsd: number;
-    totalDurationMs: number;
-    errorMessage?: string;
-}
-interface EvalRunsExportConfig {
-    /** Bearer key — tenant is resolved server-side from it. Reads TANGLE_API_KEY. */
-    apiKey?: string;
-    /** Intelligence base. Reads INTELLIGENCE_BASE env, else prod. */
-    base?: string;
-    /** Idempotency-Key header (e.g. the runId) — safe retries + upsert. */
-    idempotencyKey?: string;
-}
-interface EvalRunsExportResult {
-    ok: boolean;
-    status: number;
-    accepted: number;
-    rejected: Array<{
-        index: number;
-        reason: string;
-    }>;
-}
-/**
- * Ship self-improvement eval-run events to Tangle Intelligence. Unlike the
- * best-effort span exporter, this RESOLVES with the ingest verdict (accepted /
- * rejected per event) so a consumer's loop can assert its provenance landed.
- * Throws only on a missing key or network failure.
- */
-declare function exportEvalRuns(events: EvalRunEvent[], config?: EvalRunsExportConfig): Promise<EvalRunsExportResult>;
-
-export { type EvalRunEvent as E, INTELLIGENCE_WIRE_VERSION as I, type OtelExporter as O, mcpToolsForRuntimeMcpSubset as a, type EvalRunGeneration as b, type EvalRunsExportConfig as c, type EvalRunsExportResult as d, type OtelAttribute as e, type OtelExportConfig as f, type OtelSpan as g, buildLoopOtelSpans as h, createOtelExporter as i, exportEvalRuns as j, loopEventToOtelSpan as l, mcpToolsForRuntimeMcp as m };

package/dist/runtime-run-B8VIiOhI.d.ts

@@ -1,137 +0,0 @@
-import { A as AgentTaskSpec, R as RuntimeStreamEvent } from './types-CsCCryln.js';
-
-/**
- * @stable
- *
- * Production-run lifecycle: record what the agent did on behalf of a customer,
- * what it cost, and how it ended.
- *
- * Three concerns live in this module:
- *
- *  1. **Lifecycle state machine** — `running` -> `completed | failed | cancelled`,
- *     enforced by `RuntimeRunStateError`. Completion is idempotent for the same
- *     status (a second `complete()` call is a no-op so retries / cleanup paths
- *     don't double-fire side effects). A different terminal status is a state
- *     error.
- *
- *  2. **Cost ledger** — every `llm_call` event the handle observes contributes
- *     `tokensIn`, `tokensOut`, `costUsd`, and bumps `llmCalls`. Wall time is
- *     measured from `startRuntimeRun()` to `complete()`. Surface via
- *     `handle.cost()` for cost-per-task dashboards.
- *
- *  3. **Persistence adapter** — `RuntimeRunPersistenceAdapter` is the seam
- *     consumers plug in to write a `RuntimeRunRow` to their D1 / postgres /
- *     KV store. The adapter receives a sanitized row shape; no telemetry
- *     payload bytes flow through it unless the consumer opts in via
- *     `RuntimeRunOptions.telemetryEvents`.
- */
-
-/** @stable */
-type RuntimeRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
-/** @stable */
-interface RuntimeRunCost {
-    /** Cumulative input tokens across every observed `llm_call` event. */
-    tokensIn: number;
-    /** Cumulative output tokens across every observed `llm_call` event. */
-    tokensOut: number;
-    /** Sum of `costUsd` from every observed `llm_call` event. */
-    costUsd: number;
-    /** Wall time from `startRuntimeRun()` to `complete()` (or `now()` if not yet completed). */
-    wallMs: number;
-    /** Count of `llm_call` events observed during the run. */
-    llmCalls: number;
-}
-/** @stable */
-interface RuntimeRunCompleteInput {
-    status: Exclude<RuntimeRunStatus, 'running'>;
-    resultSummary?: string;
-    /** Optional explicit cost override; if omitted, the accumulated ledger is used. */
-    cost?: Partial<RuntimeRunCost>;
-    /** Stable error message when `status === 'failed'`. */
-    error?: string;
-    /** Additional adapter-specific fields merged into the persisted row. */
-    metadata?: Record<string, unknown>;
-}
-/** @stable */
-interface RuntimeRunRow {
-    /** Stable runtime-side identifier. Adapters may translate to their own primary key. */
-    id: string;
-    workspaceId: string;
-    sessionId?: string;
-    agentId?: string;
-    domain?: string;
-    taskId: string;
-    scenarioId?: string;
-    status: RuntimeRunStatus;
-    resultSummary?: string;
-    error?: string;
-    cost: RuntimeRunCost;
-    startedAt: string;
-    completedAt?: string;
-    metadata?: Record<string, unknown>;
-}
-/** @stable */
-interface RuntimeRunPersistenceAdapter {
-    /**
-     * Called once when `handle.persist()` runs. Implementations write `row` to
-     * their durable store (D1, postgres, KV) and return whatever the consumer
-     * wants the caller to see (often the storage-side row id). Errors thrown
-     * here propagate out of `persist()` so the caller can decide whether to
-     * retry or log-and-continue.
-     */
-    upsert(row: RuntimeRunRow): Promise<void> | void;
-}
-/** @stable */
-interface RuntimeRunOptions {
-    workspaceId: string;
-    sessionId?: string;
-    agentId?: string;
-    taskSpec: AgentTaskSpec;
-    scenarioId?: string;
-    /** Optional persistence adapter; if omitted, `persist()` is a no-op. */
-    adapter?: RuntimeRunPersistenceAdapter;
-    /** Override the row id; default = `${taskSpec.id}:${random suffix}`. */
-    id?: string;
-    /** Override the clock; default = `Date.now()`. Useful for deterministic tests. */
-    now?: () => number;
-}
-/** @stable */
-interface RuntimeRunHandle {
-    /** Stable id assigned at start. */
-    readonly id: string;
-    readonly workspaceId: string;
-    readonly sessionId: string | undefined;
-    readonly taskSpec: AgentTaskSpec;
-    readonly status: RuntimeRunStatus;
-    /**
-     * Observe a single `RuntimeStreamEvent`. The handle ignores non-cost events
-     * (text deltas, tool calls) silently so consumers can pipe the whole stream
-     * through `handle.observe`. `llm_call` events update the ledger.
-     */
-    observe(event: RuntimeStreamEvent): void;
-    /** Snapshot of the current cost ledger. Safe to call at any time. */
-    cost(): RuntimeRunCost;
-    /**
-     * Transition to a terminal state. Idempotent for the same status; throws
-     * `RuntimeRunStateError` for a different terminal status (state machines
-     * don't time-travel).
-     */
-    complete(input: RuntimeRunCompleteInput): void;
-    /** Build the current row without writing it. Useful for tests + dry runs. */
-    toRow(metadata?: Record<string, unknown>): RuntimeRunRow;
-    /**
-     * Persist the current row via the configured adapter. Must be called after
-     * `complete()`. Idempotent for the same terminal state (the adapter sees
-     * the same row on retry).
-     */
-    persist(metadata?: Record<string, unknown>): Promise<void>;
-}
-/**
- * @stable
- *
- * Construct a runtime-run handle. The returned handle is mutable across its
- * lifetime; consumers should not share it across requests.
- */
-declare function startRuntimeRun(options: RuntimeRunOptions): RuntimeRunHandle;
-
-export { type RuntimeRunHandle as R, type RuntimeRunPersistenceAdapter as a, type RuntimeRunRow as b, startRuntimeRun as s };