@infinityi/engine-lib 1.0.0

package/dist/agent/handoff.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Handoff / delegation helpers (Phase 7).
+ *
+ * A handoff lets one agent transfer the running conversation to another
+ * (triage → specialist) while keeping the message history intact. Rather than
+ * inventing a new protocol, each declared {@link AgentDefinition.handoffs}
+ * target is surfaced to the model as a synthetic `transfer_to_<name>` tool
+ * (Principle 1, provider-native): when the model calls it, the run loop
+ * acknowledges the tool call, emits `agent.handoff`, and switches the *active
+ * agent* instead of dispatching a normal tool.
+ *
+ * This module only computes the synthetic toolset and resolves targets; the
+ * active-agent switch lives in the run loop (`executeAgent`).
+ *
+ * @module
+ */
+import type { ProviderTool } from "../providers/types";
+import type { AgentRegistry } from "./agent-registry";
+import type { AgentDefinition } from "./types";
+/** Prefix for the synthetic tools the loop advertises for an agent's handoffs. */
+export declare const HANDOFF_TOOL_PREFIX = "transfer_to_";
+/** The synthetic transfer-tool name for a target agent. */
+export declare function handoffToolName(agentName: string): string;
+/**
+ * Resolve an agent's declared {@link AgentDefinition.handoffs} into a map keyed
+ * by synthetic transfer-tool name (`transfer_to_<name>`). String targets are
+ * resolved through `registry`.
+ *
+ * @throws {ExecutionError} if a string target is declared without a registry,
+ *   the target name is unknown, or two targets resolve to the same name. The
+ *   run loop also rejects synthetic handoff tool names that collide with a real
+ *   tool on the same agent.
+ */
+export declare function resolveHandoffTargets(agent: AgentDefinition, registry?: AgentRegistry): Map<string, AgentDefinition>;
+/**
+ * Synthesize the provider-advertised transfer tools for a resolved target map
+ * (as produced by {@link resolveHandoffTargets}).
+ */
+export declare function handoffProviderTools(targets: ReadonlyMap<string, AgentDefinition>): ProviderTool[];

package/dist/agent/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@infinityi/engine-lib/agent` — the agent contract: declarative {@link AgentDefinition}s,
+ * the {@link defineAgent} constructor, and the per-agent {@link ToolRegistry}.
+ *
+ * Re-exports the tool contract too, so the common path (define a tool, define an
+ * agent) is reachable from a single import.
+ *
+ * @module
+ */
+export { defineAgent } from "./define";
+export { createToolRegistry } from "./registry";
+export type { ToolRegistry } from "./registry";
+export { createAgentRegistry } from "./agent-registry";
+export type { AgentRegistry } from "./agent-registry";
+export { asTool } from "./as-tool";
+export type { AsToolOptions } from "./as-tool";
+export { handoffProviderTools, handoffToolName, resolveHandoffTargets } from "./handoff";
+export type { AgentDefinition, AgentHooks, GenerationSettings, InstructionContext, Instructions, } from "./types";
+export { defineTool, renderToolContent, toProviderTool, toToolResultMessage } from "../tools/index";
+export type { ToolContext, ToolDefinition, ToolFailure, ToolResult, ToolSpec, ToolSuccess, } from "../tools/index";

package/dist/agent/index.js

@@ -0,0 +1,38 @@
+import {
+  asTool,
+  createAgentRegistry,
+  defineAgent
+} from "../index-jp2b31xs.js";
+import {
+  createToolRegistry,
+  handoffProviderTools,
+  handoffToolName,
+  resolveHandoffTargets
+} from "../index-pwr8179t.js";
+import"../index-yrqrxwjt.js";
+import"../index-fkr3rcq9.js";
+import"../index-02s1fjxr.js";
+import"../index-zfgr4xx3.js";
+import"../index-7690reng.js";
+import {
+  defineTool
+} from "../index-w34cbktd.js";
+import {
+  renderToolContent,
+  toProviderTool,
+  toToolResultMessage
+} from "../index-rentvdpp.js";
+import"../index-1p6mb2vz.js";
+export {
+  toToolResultMessage,
+  toProviderTool,
+  resolveHandoffTargets,
+  renderToolContent,
+  handoffToolName,
+  handoffProviderTools,
+  defineTool,
+  defineAgent,
+  createToolRegistry,
+  createAgentRegistry,
+  asTool
+};

package/dist/agent/registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The per-agent tool registry.
+ *
+ * A {@link ToolRegistry} provides name-based lookup over an agent's toolset and
+ * generates the provider-facing JSON-Schema toolset. It is built eagerly so
+ * duplicate tool names fail fast (a configuration bug), rather than surfacing as
+ * a confusing mid-run dispatch error.
+ *
+ * @module
+ */
+import type { ProviderTool } from "../providers/types";
+import type { ToolDefinition } from "../tools/types";
+/** Name-based lookup over a toolset, plus provider-toolset generation. */
+export interface ToolRegistry {
+    readonly size: number;
+    has(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    list(): readonly ToolDefinition[];
+    /** Project every tool into a Phase-2 {@link ProviderTool}, preserving order. */
+    toProviderTools(): ProviderTool[];
+}
+/**
+ * Build a {@link ToolRegistry} from a toolset.
+ *
+ * @throws {ExecutionError} if two tools share a name.
+ */
+export declare function createToolRegistry(tools: readonly ToolDefinition[]): ToolRegistry;

package/dist/agent/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The agent contract — a declarative description of *what* an agent is.
+ *
+ * An {@link AgentDefinition} is plain data, not a class hierarchy: which
+ * {@link Provider} to call, what {@link Instructions} to send, which
+ * {@link ToolDefinition tools} the model may invoke, the default
+ * {@link GenerationSettings generation settings}, and {@link AgentHooks}
+ * lifecycle slots. The stable application path is `defineAgent`; hand-written
+ * {@link AgentDefinition} objects are mainly useful for tests and adapters.
+ * Definitions are data only: the run loop resolves instructions, invokes
+ * hooks, advertises tools, and performs handoffs.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { CompletionResult, Provider, ToolCall, ToolChoice, Usage } from "../providers/types";
+import type { EngineContext } from "../runtime/types";
+import type { AgentError } from "../errors";
+import type { ToolDefinition, ToolResult } from "../tools/types";
+/**
+ * Default per-turn generation knobs an agent applies to each provider call.
+ * A subset of the Phase-2 `CompletionRequest`; the run loop merges these in,
+ * letting per-run overrides win.
+ */
+export interface GenerationSettings {
+    /** Model id; falls back to the provider's `defaultModel` when omitted. */
+    readonly model?: string;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly maxOutputTokens?: number;
+    readonly stopSequences?: readonly string[];
+    /** How the model may use tools this turn. */
+    readonly toolChoice?: ToolChoice;
+}
+/** Context available to dynamic {@link Instructions}. */
+export interface InstructionContext extends EngineContext {
+    readonly agent: AgentDefinition;
+}
+/**
+ * System instructions: a static string, or a function of run context resolved
+ * at run time so the host can fold in per-run facts. Resolved instructions are
+ * injected into the system layer for the provider request, but are not persisted
+ * to sessions.
+ */
+export type Instructions = string | ((ctx: InstructionContext) => string | Promise<string>);
+/**
+ * Lifecycle hook slots. Declared here on the agent; the run loop invokes them
+ * at well-defined points. All hooks are optional, awaited, and receive the
+ * shared engine context.
+ *
+ * Public `RunEvent`s are emitted before the corresponding hook is invoked.
+ * Hook failures fail the run and are routed through `onError`; an `onError`
+ * failure never replaces the original run failure.
+ */
+export interface AgentHooks {
+    /** Before the first provider call. */
+    onStart?(event: {
+        agent: AgentDefinition;
+        messages: Message[];
+    }, ctx: EngineContext): void | Promise<void>;
+    /** After each completed provider turn. */
+    onStep?(event: {
+        step: number;
+        result: CompletionResult;
+    }, ctx: EngineContext): void | Promise<void>;
+    /** Before a validated tool call is dispatched. */
+    onToolCall?(event: {
+        call: ToolCall;
+        tool: ToolDefinition;
+    }, ctx: EngineContext): void | Promise<void>;
+    /** After a tool produces a result. */
+    onToolResult?(event: {
+        call: ToolCall;
+        result: ToolResult;
+    }, ctx: EngineContext): void | Promise<void>;
+    /** When the run produces its final answer. */
+    onFinish?(event: {
+        output: string;
+        usage?: Usage;
+    }, ctx: EngineContext): void | Promise<void>;
+    /** When the run fails. */
+    onError?(event: {
+        error: AgentError;
+    }, ctx: EngineContext): void | Promise<void>;
+    /** When this agent hands the run off to another agent (Phase 7). */
+    onHandoff?(event: {
+        from: AgentDefinition;
+        to: AgentDefinition;
+    }, ctx: EngineContext): void | Promise<void>;
+}
+/** A declarative agent definition — data describing behavior, executed by the runtime. */
+export interface AgentDefinition {
+    readonly name: string;
+    readonly provider: Provider;
+    readonly instructions?: Instructions;
+    readonly tools?: readonly ToolDefinition[];
+    /**
+     * Agents this one may hand the run off to (Phase 7). Each target becomes a
+     * synthetic `transfer_to_<name>` tool the model can call to switch the active
+     * agent. A target may be given directly as an {@link AgentDefinition}, or by
+     * name as a `string` resolved through the {@link AgentRegistry} passed in
+     * `RunOptions.registry`. String targets without a registry fail the run.
+     */
+    readonly handoffs?: readonly (AgentDefinition | string)[];
+    /** Default generation settings applied to each turn. */
+    readonly generation?: GenerationSettings;
+    /** Lifecycle hook slots. */
+    readonly hooks?: AgentHooks;
+}

package/dist/context/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@infinityi/engine-lib/context` — run-time context injection ({@link staticContext},
+ * {@link dynamicContext}) and context-window management ({@link truncateOldest},
+ * {@link summarizeOldest}, {@link estimateTokens}). engine-lib injects context and
+ * keeps history within budget; the host owns the content and retrieval.
+ *
+ * @module
+ */
+export { dynamicContext, resolveContext, staticContext } from "./providers";
+export { applyContextWindow, estimateTokens, summarizeOldest, truncateOldest, } from "./window";
+export type { ContextItem, ContextProvider, ContextStrategy, ContextStrategyContext, ContextWindowOptions, TokenCounter, } from "./types";

package/dist/context/index.js

@@ -0,0 +1,21 @@
+import"../index-d4xz3abn.js";
+import {
+  applyContextWindow,
+  dynamicContext,
+  estimateTokens,
+  resolveContext,
+  staticContext,
+  summarizeOldest,
+  truncateOldest
+} from "../index-yrqrxwjt.js";
+import"../index-7690reng.js";
+import"../index-1p6mb2vz.js";
+export {
+  truncateOldest,
+  summarizeOldest,
+  staticContext,
+  resolveContext,
+  estimateTokens,
+  dynamicContext,
+  applyContextWindow
+};

package/dist/context/providers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in {@link ContextProvider}s and the resolver that turns them into the
+ * system messages injected at the head of a run. Context providers are resolved
+ * once per run, before the first provider call; their output is never persisted
+ * to a session.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { EngineContext } from "../runtime/types";
+import type { ContextProvider } from "./types";
+/**
+ * Inject static facts verbatim. `content` is rendered as-is (strings) or
+ * JSON-encoded; an optional `title` becomes a markdown heading.
+ */
+export declare function staticContext(content: unknown, title?: string): ContextProvider;
+/** Inject context computed lazily at run time from the {@link EngineContext}. */
+export declare function dynamicContext(name: string, fn: (ctx: EngineContext) => unknown | Promise<unknown>, title?: string): ContextProvider;
+/**
+ * Resolve all providers and fold their items into a single `system` message
+ * (the injected-context block), or `[]` when there is nothing to inject.
+ * Providers resolve concurrently; their declaration order is preserved in the
+ * output.
+ */
+export declare function resolveContext(providers: readonly ContextProvider[] | undefined, ctx: EngineContext): Promise<Message[]>;

package/dist/context/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Context injection + context-window management contracts.
+ *
+ * A {@link ContextProvider} supplies run-time facts (system state, retrieved
+ * documents, environment) that engine-lib merges into the system layer of a run —
+ * the library *injects*; the host decides the content (no RAG engine). A
+ * {@link ContextStrategy} keeps the growing history within the model's window via
+ * pluggable token-budgeting (truncate / summarize), raising
+ * `ContextWindowError` only when the history is irreducible. Window strategies
+ * reduce the request view sent to the provider; they must not mutate persisted
+ * or returned session history.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { Provider } from "../providers/types";
+import type { EngineContext } from "../runtime/types";
+/** A unit of injected context, rendered into a system message at run time. */
+export interface ContextItem {
+    /** Optional heading shown before the rendered content. */
+    readonly title?: string;
+    /** Strings pass through; anything else is JSON-encoded when rendered. */
+    readonly content: unknown;
+}
+/**
+ * A host-supplied context source, resolved once per run before the first
+ * provider call. Results are injected as system context and are not persisted.
+ */
+export interface ContextProvider {
+    readonly name: string;
+    resolve(ctx: EngineContext): ContextItem[] | Promise<ContextItem[]>;
+}
+/** Counts tokens for a message list (pluggable; a char-based heuristic ships built-in). */
+export type TokenCounter = (messages: readonly Message[]) => number;
+/** Inputs a {@link ContextStrategy} needs to reduce history (besides the messages). */
+export interface ContextStrategyContext {
+    readonly maxTokens: number;
+    readonly countTokens: TokenCounter;
+    /** Provider available to strategies that need a model call (e.g. summarize). */
+    readonly provider: Provider;
+    readonly model: string;
+    readonly engine: EngineContext;
+}
+/** A pluggable history-reduction policy for the provider request view. */
+export interface ContextStrategy {
+    readonly name: string;
+    /**
+     * Reduce `messages` so `countTokens(result) <= maxTokens`. Must preserve
+     * conversational validity (for example, keep required system messages).
+     * Return a new request view and throw `ContextWindowError` when the history
+     * cannot be reduced to fit.
+     */
+    reduce(messages: Message[], ctx: ContextStrategyContext): Message[] | Promise<Message[]>;
+}
+/** Per-run context-window budgeting configuration. */
+export interface ContextWindowOptions {
+    /** Maximum tokens the assembled request may consume. */
+    readonly maxTokens: number;
+    /** Reduction policy; defaults to `truncateOldest()`. */
+    readonly strategy?: ContextStrategy;
+    /** Token counter; defaults to {@link estimateTokens}. */
+    readonly countTokens?: TokenCounter;
+}

package/dist/context/window.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Context-window management: a default token estimator, two built-in reduction
+ * strategies ({@link truncateOldest}, {@link summarizeOldest}), and
+ * {@link applyContextWindow} which produces the (possibly trimmed) message view
+ * sent to the provider without mutating the canonical history.
+ *
+ * {@link truncateOldest} is the stable default. {@link summarizeOldest} is also
+ * public, but it performs an additional provider call and should be chosen
+ * deliberately when summarization is acceptable.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { ContextStrategy, ContextStrategyContext, ContextWindowOptions } from "./types";
+/**
+ * Default {@link TokenCounter}: a provider-agnostic heuristic of ~4 chars/token
+ * over all message text. Swap in a real tokenizer via `ContextWindowOptions.countTokens`.
+ */
+export declare function estimateTokens(messages: readonly Message[]): number;
+/**
+ * Drop the oldest non-`system` messages until the history fits `maxTokens`.
+ * System messages are always retained; if they alone exceed the budget the
+ * history is irreducible and {@link ContextWindowError} is thrown. This is the
+ * default stable context-window strategy.
+ */
+export declare function truncateOldest(): ContextStrategy;
+/**
+ * Compress the oldest overflow into a single `system` summary via a provider
+ * call, keeping the most recent `keepRecent` (default 4) non-system messages
+ * verbatim. Throws {@link ContextWindowError} if the result still overflows.
+ */
+export declare function summarizeOldest(opts?: {
+    keepRecent?: number;
+}): ContextStrategy;
+/**
+ * Produce the message view to send to the provider. Returns `messages` unchanged
+ * when no `window` is configured or the history already fits; otherwise applies
+ * the configured (or default `truncateOldest`) strategy. Never mutates the input
+ * or persisted session history.
+ */
+export declare function applyContextWindow(messages: Message[], window: ContextWindowOptions | undefined, ctx: Pick<ContextStrategyContext, "provider" | "model" | "engine">): Promise<Message[]>;

package/dist/errors.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Typed error taxonomy for `@infinityi/engine-lib`.
+ *
+ * Every error the library throws is a subclass of {@link AgentError},
+ * so consumers can branch with a single `instanceof AgentError` check
+ * or narrow to a specific category.
+ *
+ * The full hierarchy is defined up-front so later phases import stable
+ * symbols; only {@link SchemaValidationError} and
+ * {@link ToolValidationError} are thrown by Phase-1 code.
+ *
+ * @module
+ */
+import type { Usage } from "./providers/types";
+/** Structured validation issue attached to {@link SchemaValidationError}. */
+export interface SchemaIssue {
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+}
+/**
+ * Base class for every error thrown by `@infinityi/engine-lib`.
+ * `instanceof AgentError` catches the entire family.
+ */
+export declare class AgentError extends Error {
+    /**
+     * Token usage accumulated before the run failed, when known. The run loop
+     * stamps this onto the error it throws so a failed `runAgent` (or a failed
+     * sub-agent invoked via `asTool`) still surfaces the tokens it consumed
+     * rather than silently dropping them.
+     */
+    usage?: Usage;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A provider / LLM call failed (HTTP, protocol, refusal). */
+export declare class ProviderError extends AgentError {
+    readonly provider?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        provider?: string;
+    });
+}
+/** A tool's `execute` function threw (as opposed to returning an error result). */
+export declare class ToolError extends AgentError {
+    readonly toolName?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        toolName?: string;
+    });
+}
+/** Input failed schema validation. Carries machine-readable {@link SchemaIssue}s. */
+export declare class SchemaValidationError extends AgentError {
+    readonly issues: ReadonlyArray<SchemaIssue>;
+    constructor(message: string, options: ErrorOptions & {
+        issues: SchemaIssue[];
+    });
+}
+/** Tool-call arguments from the model failed the tool's parameter schema. */
+export declare class ToolValidationError extends SchemaValidationError {
+    readonly toolName?: string;
+    constructor(message: string, options: ErrorOptions & {
+        toolName?: string;
+        issues: SchemaIssue[];
+    });
+}
+/** The run loop / execution failed for a non-provider, non-tool reason. */
+export declare class ExecutionError extends AgentError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The model exceeded the configured max step / turn budget. */
+export declare class MaxStepsExceededError extends ExecutionError {
+    readonly steps?: number;
+    constructor(message: string, options?: ErrorOptions & {
+        steps?: number;
+    });
+}
+/** The run exceeded the configured maximum number of agent handoffs. */
+export declare class MaxHandoffsExceededError extends ExecutionError {
+    readonly handoffs?: number;
+    constructor(message: string, options?: ErrorOptions & {
+        handoffs?: number;
+    });
+}
+/** The run was aborted via `AbortSignal`. */
+export declare class CancelledError extends AgentError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** History cannot be reduced to fit the model context window. */
+export declare class ContextWindowError extends AgentError {
+    readonly tokens?: number;
+    readonly limit?: number;
+    constructor(message: string, options?: ErrorOptions & {
+        tokens?: number;
+        limit?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+import {
+  AgentError,
+  CancelledError,
+  ContextWindowError,
+  ExecutionError,
+  MaxHandoffsExceededError,
+  MaxStepsExceededError,
+  ProviderError,
+  SchemaValidationError,
+  ToolError,
+  ToolValidationError
+} from "./index-7690reng.js";
+export {
+  ToolValidationError,
+  ToolError,
+  SchemaValidationError,
+  ProviderError,
+  MaxStepsExceededError,
+  MaxHandoffsExceededError,
+  ExecutionError,
+  ContextWindowError,
+  CancelledError,
+  AgentError
+};

package/dist/events/hub.d.ts

@@ -0,0 +1,15 @@
+/**
+ * {@link createEventHub} — the multi-subscriber fan-out used by the run loop.
+ *
+ * Dispatch is ordered and awaited: each subscriber sees every event in the
+ * order they were registered, and the next event is not delivered until the
+ * current one has been handed to every subscriber. Each subscriber is
+ * isolated: a throw/rejection is routed to `onSubscriberError` and
+ * swallowed, so one misbehaving subscriber can neither abort the run nor
+ * prevent the others from observing the event.
+ *
+ * @module
+ */
+import type { EventHub, EventHubOptions } from "./types";
+/** Build an {@link EventHub} from a fixed list of subscribers. */
+export declare function createEventHub(opts?: EventHubOptions): EventHub;

package/dist/events/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@infinityi/engine-lib/events` — the event system & telemetry bridge (Phase 6).
+ *
+ * The run loop already emits a typed {@link RunEvent} stream (Phase 4). This
+ * module adds:
+ *
+ * - {@link createEventHub} — fan a single run's events out to **multiple
+ *   independent subscribers** with ordered, isolated delivery.
+ * - {@link loggingSubscriber} / {@link messageBusSubscriber} — ready-made sinks
+ *   for forge `Logger` and `MessageBus`.
+ * - {@link createRunTelemetry} — automatic `forge/telemetry` spans + metrics for
+ *   runs, provider calls, and tool calls.
+ *
+ * Wire subscribers via {@link RunOptions.subscribers}; telemetry is enabled
+ * automatically whenever a {@link RunOptions.telemetry} handle is supplied.
+ * The root package exports subscriber factories, while this subpath also
+ * exposes event projection and telemetry helpers for integrations.
+ *
+ * @module
+ */
+export { createEventHub } from "./hub";
+export type { EventHub, EventHubOptions, RunSubscriber } from "./types";
+export { eventFields, eventPayload, loggingSubscriber, messageBusSubscriber, } from "./subscribers";
+export type { LoggingSubscriberOptions, LogLevel, MessageBusSubscriberOptions, } from "./subscribers";
+export { createRunTelemetry, SPAN_PROVIDER, SPAN_RUN, SPAN_TOOL } from "./telemetry";
+export type { Attrs, RunTelemetry, SpanHandle } from "./telemetry";

package/dist/events/index.js

@@ -0,0 +1,24 @@
+import {
+  eventFields,
+  eventPayload,
+  loggingSubscriber,
+  messageBusSubscriber
+} from "../index-jxgj4z08.js";
+import {
+  SPAN_PROVIDER,
+  SPAN_RUN,
+  SPAN_TOOL,
+  createEventHub,
+  createRunTelemetry
+} from "../index-fkr3rcq9.js";
+export {
+  messageBusSubscriber,
+  loggingSubscriber,
+  eventPayload,
+  eventFields,
+  createRunTelemetry,
+  createEventHub,
+  SPAN_TOOL,
+  SPAN_RUN,
+  SPAN_PROVIDER
+};

package/dist/events/subscribers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Built-in {@link RunSubscriber} factories and event projection helpers.
+ *
+ * These are optional conveniences for the common external sinks. They depend
+ * only on forge contracts (`Logger`, `MessageBus`) the host already owns, so
+ * engine-lib never forces a transport or a logging backend on you.
+ * `eventFields` and `eventPayload` are stable on the `@infinityi/engine-lib/events`
+ * subpath for custom subscribers, but intentionally not exported from the root
+ * barrel.
+ *
+ * @module
+ */
+import type { MessageBus } from "@infinityi/forge/messaging";
+import type { RunEvent } from "../execution/types";
+import type { Logger } from "../runtime/types";
+import type { RunSubscriber } from "./types";
+/** Log severities a {@link loggingSubscriber} may emit at. */
+export type LogLevel = "trace" | "debug" | "info";
+/** Options for {@link loggingSubscriber}. */
+export interface LoggingSubscriberOptions {
+    /** Severity for each event line. Defaults to `"debug"`. */
+    readonly level?: LogLevel;
+}
+/**
+ * A subscriber that writes one structured log line per {@link RunEvent} via a
+ * forge {@link Logger}. It logs compact fields from {@link eventFields}, not
+ * the full event payload.
+ */
+export declare function loggingSubscriber(logger: Logger, opts?: LoggingSubscriberOptions): RunSubscriber;
+/** Options for {@link messageBusSubscriber}. */
+export interface MessageBusSubscriberOptions {
+    /** Prefix prepended to each message `type`. Defaults to `"agent."`. */
+    readonly typePrefix?: string;
+}
+/**
+ * A subscriber that republishes every {@link RunEvent} onto a forge
+ * {@link MessageBus} (e.g. `agent.run.start`, `agent.tool.call`). The payload
+ * is a serialization-safe projection of the event (see {@link eventPayload}).
+ * Publish is awaited; a failing publish surfaces through the hub's subscriber
+ * isolation rather than aborting the run.
+ */
+export declare function messageBusSubscriber(bus: MessageBus, opts?: MessageBusSubscriberOptions): RunSubscriber;
+/**
+ * Compact, log-friendly fields describing an event (no large payloads).
+ *
+ * This is a stable projection helper for custom subscribers; it is not the full
+ * event object.
+ */
+export declare function eventFields(event: RunEvent): Record<string, string | number | boolean>;
+/**
+ * A JSON-serializable projection of an event, for publishing onto a bus.
+ *
+ * This projection is intentionally smaller and more serialization-friendly than
+ * the full {@link RunEvent}; custom subscribers that need exact event objects
+ * should consume `RunEvent` directly.
+ */
+export declare function eventPayload(event: RunEvent): Record<string, unknown>;