@graphorin/core 0.5.0

package/dist/types/agent-event.d.ts

@@ -0,0 +1,449 @@
+import { Usage } from "./usage.js";
+import { ContentChunk, ToolError } from "./tool.js";
+import { RunError, RunState, RunStatus } from "./run.js";
+
+//#region src/types/agent-event.d.ts
+
+/**
+ * Discriminated union of every event produced by `Agent.stream(...)`.
+ *
+ * Each variant has a literal `type` field used as the discriminator. The
+ * union is exhaustive: `assertNever(...)` catches missed variants at
+ * compile time.
+ *
+ * The shape is wire-stable: the protocol package (`@graphorin/protocol`,
+ * created in a later phase) re-exports this union as its server-to-client
+ * payload schema. Adding a variant here therefore counts as a wire-format
+ * change; track it through changesets.
+ *
+ * @stable
+ */
+type AgentEvent<TOutput = string> = AgentStartEvent | StepStartEvent | TextDeltaEvent | TextCompleteEvent | ReasoningDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | ToolExecuteStartEvent | ToolExecuteProgressEvent | ToolExecutePartialEvent | ToolExecuteEndEvent | ToolExecuteErrorEvent | ToolApprovalRequestedEvent | ToolApprovalGrantedEvent | ToolApprovalDeniedEvent | ContextCompactedEvent | HandoffEvent | AgentSteeredEvent | AgentFollowUpQueuedEvent | AgentCancellingEvent | AgentModelFellbackEvent | AgentFanOutSpawnedEvent | AgentFanOutMergedEvent | AgentEvaluatorIterationEvent | AgentEvaluatorConvergedEvent | AgentProgressWrittenEvent | AgentProgressReadEvent | AgentLateralLeakDetectedEvent | FileGeneratedEvent | SourceCitedEvent | StepEndEvent | GuardrailTrippedEvent | AgentEndEvent<TOutput> | AgentErrorEvent;
+/** @stable */
+interface AgentStartEvent {
+  readonly type: 'agent.start';
+  readonly runId: string;
+  readonly agentId: string;
+}
+/** @stable */
+interface StepStartEvent {
+  readonly type: 'step.start';
+  readonly stepNumber: number;
+}
+/** @stable */
+interface TextDeltaEvent {
+  readonly type: 'text.delta';
+  readonly delta: string;
+}
+/** @stable */
+interface TextCompleteEvent {
+  readonly type: 'text.complete';
+  readonly text: string;
+}
+/** @stable */
+interface ReasoningDeltaEvent {
+  readonly type: 'reasoning.delta';
+  readonly delta: string;
+}
+/** @stable */
+interface ToolCallStartEvent {
+  readonly type: 'tool.call.start';
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+}
+/** @stable */
+interface ToolCallDeltaEvent {
+  readonly type: 'tool.call.delta';
+  readonly toolCallId: string;
+  readonly argsDelta: string;
+}
+/** @stable */
+interface ToolCallEndEvent {
+  readonly type: 'tool.call.end';
+  readonly toolCallId: string;
+  readonly finalArgs: unknown;
+}
+/** @stable */
+interface ToolExecuteStartEvent {
+  readonly type: 'tool.execute.start';
+  readonly toolCallId: string;
+}
+/**
+ * Emitted by streaming-hint tools via `ctx.reportProgress(...)`. Counter
+ * pair `(current, total?)` is consumer-rendered as a percentage when both
+ * fields are present.
+ *
+ * @stable
+ */
+interface ToolExecuteProgressEvent {
+  readonly type: 'tool.execute.progress';
+  readonly toolName: string;
+  readonly toolCallId: string;
+  readonly current: number;
+  readonly total?: number;
+  readonly message?: string;
+  readonly stepNumber: number;
+  readonly ts: number;
+}
+/**
+ * Emitted by streaming-hint tools via `ctx.streamContent(...)`. Each
+ * chunk is concatenated into the assembled `output` per the
+ * buffer-becomes-output discipline. `chunkIndex` is monotone per
+ * `(toolCallId)` so subscribers can detect drops.
+ *
+ * @stable
+ */
+interface ToolExecutePartialEvent {
+  readonly type: 'tool.execute.partial';
+  readonly toolName: string;
+  readonly toolCallId: string;
+  readonly chunk: ContentChunk;
+  readonly chunkIndex: number;
+  readonly stepNumber: number;
+  readonly ts: number;
+}
+/** @stable */
+interface ToolExecuteEndEvent {
+  readonly type: 'tool.execute.end';
+  readonly toolCallId: string;
+  readonly result: unknown;
+  readonly durationMs: number;
+}
+/** @stable */
+interface ToolExecuteErrorEvent {
+  readonly type: 'tool.execute.error';
+  readonly toolCallId: string;
+  readonly error: ToolError;
+}
+/** @stable */
+interface ToolApprovalRequestedEvent {
+  readonly type: 'tool.approval.requested';
+  readonly toolCallId: string;
+  readonly reason?: string;
+}
+/** @stable */
+interface ToolApprovalGrantedEvent {
+  readonly type: 'tool.approval.granted';
+  readonly toolCallId: string;
+}
+/** @stable */
+interface ToolApprovalDeniedEvent {
+  readonly type: 'tool.approval.denied';
+  readonly toolCallId: string;
+  readonly reason?: string;
+}
+/**
+ * Emitted when the runtime auto-compacts the in-flight session
+ * message-history to fit the context window.
+ *
+ * @stable
+ */
+interface ContextCompactedEvent {
+  readonly type: 'context.compacted';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly beforeTokens: number;
+  readonly afterTokens: number;
+  readonly summaryTokens: number;
+  readonly durationMs: number;
+  readonly source: 'auto-trigger' | 'manual' | 'pre-step';
+  readonly hooksFiredCount: number;
+}
+/** @stable */
+interface HandoffEvent {
+  readonly type: 'handoff';
+  readonly fromAgentId: string;
+  readonly toAgentId: string;
+  readonly reason?: string;
+}
+/**
+ * A provider-generated file surfaced from the model stream (AG-26) —
+ * previously these `'file'` provider events were silently dropped.
+ *
+ * @stable
+ */
+interface FileGeneratedEvent {
+  readonly type: 'file.generated';
+  readonly mimeType: string;
+  readonly data: Uint8Array;
+}
+/**
+ * A provider citation surfaced from the model stream (AG-26) —
+ * previously these `'source'` provider events were silently dropped.
+ *
+ * @stable
+ */
+interface SourceCitedEvent {
+  readonly type: 'source.cited';
+  readonly uri: string;
+  readonly title?: string;
+}
+/** @stable */
+interface StepEndEvent {
+  readonly type: 'step.end';
+  readonly stepNumber: number;
+  readonly usage: Usage;
+}
+/** @stable */
+interface GuardrailTrippedEvent {
+  readonly type: 'guardrail.tripped';
+  readonly guardrailName: string;
+  readonly phase: 'input' | 'output';
+  readonly reason?: string;
+}
+/** @stable */
+interface AgentEndEvent<TOutput = string> {
+  readonly type: 'agent.end';
+  readonly runId: string;
+  readonly result: AgentResult<TOutput>;
+}
+/** @stable */
+interface AgentErrorEvent {
+  readonly type: 'agent.error';
+  readonly error: {
+    readonly message: string;
+    readonly code: string;
+  };
+}
+/**
+ * Emitted when `agent.steer(...)` queues an intervention to flow into
+ * the next provider call within the current run.
+ *
+ * @stable
+ */
+interface AgentSteeredEvent {
+  readonly type: 'agent.steered';
+  readonly runId: string;
+}
+/**
+ * Emitted when `agent.followUp(...)` queues a follow-up turn to fire
+ * after the current turn completes.
+ *
+ * @stable
+ */
+interface AgentFollowUpQueuedEvent {
+  readonly type: 'agent.followup.queued';
+  readonly runId: string;
+}
+/**
+ * Emitted at the moment `agent.abort({ ... })` is called, before any
+ * pending tool / provider calls have terminated. Subscribers use this
+ * to render "cancelling..." UI before the run actually winds down.
+ *
+ * @stable
+ */
+interface AgentCancellingEvent {
+  readonly type: 'agent.cancelling';
+  readonly runId: string;
+  readonly drain: boolean;
+  readonly onPendingApprovals: 'deny' | 'hold' | 'fail';
+}
+/**
+ * Emitted exactly once per agent-level model-fallback transition.
+ * Identifies the failed primary, the next model in
+ * `Agent.fallbackModels`, the eligible reason taxonomy, the
+ * 1-based step number and the 1-based attempt index within the step.
+ *
+ * The event fires BEFORE the new model's stream starts so that
+ * observers see the transition before any of the new model's
+ * subsequent events flow.
+ *
+ * @stable
+ */
+interface AgentModelFellbackEvent {
+  readonly type: 'agent.model.fellback';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly from: string;
+  readonly to: string;
+  readonly reason: 'rate-limit' | 'capacity' | 'context-length' | 'transient';
+  readonly stepNumber: number;
+  readonly attempt: number;
+}
+/**
+ * Emitted when `Agent.fanOut(...)` begins to spawn its sub-agents.
+ *
+ * @stable
+ */
+interface AgentFanOutSpawnedEvent {
+  readonly type: 'agent.fanout.spawned';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly fanOutId: string;
+  readonly childCount: number;
+  readonly mergeStrategyKind: 'concat' | 'first-success' | 'judge-merge' | 'custom';
+  readonly spawnedAtIso: string;
+}
+/**
+ * Per-child result entry surfaced on
+ * {@link AgentFanOutMergedEvent.childMetadata}.
+ *
+ * @stable
+ */
+interface FanOutChildMetadata {
+  readonly agentId: string;
+  readonly status: 'completed' | 'failed' | 'budget-exceeded' | 'cancelled';
+  readonly tokensUsed: number;
+  readonly toolCallCount: number;
+  readonly durationMs: number;
+}
+/**
+ * Emitted when the fan-out merge step completes.
+ *
+ * @stable
+ */
+interface AgentFanOutMergedEvent {
+  readonly type: 'agent.fanout.merged';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly fanOutId: string;
+  readonly childCount: number;
+  readonly successfulChildCount: number;
+  readonly mergeStrategyKind: 'concat' | 'first-success' | 'judge-merge' | 'custom';
+  readonly mergeDurationMs: number;
+  readonly childMetadata: ReadonlyArray<FanOutChildMetadata>;
+}
+/**
+ * Emitted per iteration of an `evaluatorOptimizer({...})` loop.
+ *
+ * @stable
+ */
+interface AgentEvaluatorIterationEvent {
+  readonly type: 'agent.evaluator.iteration';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly iteration: number;
+  readonly score: number;
+  readonly pass: boolean;
+  readonly critique: string;
+  readonly durationMs: number;
+}
+/**
+ * Emitted at the termination of an `evaluatorOptimizer({...})` loop.
+ *
+ * @stable
+ */
+interface AgentEvaluatorConvergedEvent {
+  readonly type: 'agent.evaluator.converged';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly totalIterations: number;
+  readonly finalScore: number;
+  readonly terminationReason: 'pass' | 'maxIterations' | 'generator-exhausted' | 'cancelled';
+}
+/**
+ * Reference to a persisted progress artifact returned by
+ * `agent.progress.write(...)` and `agent.progress.read(...)`.
+ *
+ * @stable
+ */
+interface ProgressArtifactRef {
+  readonly path: string;
+  readonly role: string;
+  readonly seq: number;
+  readonly sizeBytes: number;
+  readonly sensitivity: 'public' | 'internal' | 'secret';
+  readonly tags?: ReadonlyArray<string>;
+  readonly writtenAtIso: string;
+  readonly sha256: string;
+}
+/**
+ * Emitted after `agent.progress.write(...)` completes.
+ *
+ * @stable
+ */
+interface AgentProgressWrittenEvent {
+  readonly type: 'agent.progress.written';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly ref: ProgressArtifactRef;
+}
+/**
+ * Emitted after `agent.progress.read(...)` completes.
+ *
+ * @stable
+ */
+interface AgentProgressReadEvent {
+  readonly type: 'agent.progress.read';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly refs: ReadonlyArray<ProgressArtifactRef>;
+  readonly queriedRunId: string;
+  readonly queriedRole: string | undefined;
+}
+/**
+ * Lateral-leak vector classification surfaced on
+ * {@link AgentLateralLeakDetectedEvent.vector}.
+ *
+ * - `'causality-laundering'` — the assistant message references
+ *   information about a denied earlier action via an indirect chain.
+ * - `'commentary-phase'`     — operator-only commentary content was
+ *   about to escape the session-output boundary.
+ * - `'sideways-injection'`   — a low-trust child of an
+ *   `Agent.fanOut(...)` `'judge-merge'` strategy contributed
+ *   disproportionately to the merged output.
+ * - `'protocol-header'`      — control-character bytes or a
+ *   protocol-frame separator was about to escape one of the
+ *   internal-service delivery boundaries.
+ *
+ * @stable
+ */
+type LateralLeakVector = 'causality-laundering' | 'commentary-phase' | 'sideways-injection' | 'protocol-header';
+/**
+ * Emitted when the lateral-leak defense layer flags or blocks a
+ * suspected leak.
+ *
+ * @stable
+ */
+interface AgentLateralLeakDetectedEvent {
+  readonly type: 'agent.lateral-leak.detected';
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly vector: LateralLeakVector;
+  readonly severity: 'info' | 'warn' | 'block';
+  readonly causalityChain: ReadonlyArray<string>;
+  readonly messageContentSha256: string;
+  readonly matchedPattern?: string;
+  readonly decision: 'detect' | 'flag' | 'strip' | 'block';
+  readonly detectedAtIso: string;
+}
+/**
+ * Final result of an agent run-loop invocation, returned by
+ * `agent.run(...)` and carried by the `agent.end` event.
+ *
+ * A failed run **resolves** with `status: 'failed'` and the error in
+ * `error` — `agent.run(...)` does not reject on run failure (only on
+ * configuration/usage errors thrown before the loop starts). A suspended
+ * run resolves with `status: 'awaiting_approval'` and a resumable
+ * `state` (AG-9).
+ *
+ * @stable
+ */
+interface AgentResult<TOutput = string> {
+  readonly output: TOutput;
+  readonly usage: Usage;
+  /** Terminal status of this run-loop invocation. */
+  readonly status: RunStatus;
+  /** Populated when the run failed; mirrors `RunState.error`. */
+  readonly error?: RunError;
+  /**
+   * The run's final state. Resumable when `status === 'awaiting_approval'`
+   * — pass it back to `agent.run(...)` / `agent.stream(...)` (optionally
+   * round-tripped through `runStateToJSON`/`runStateFromJSON` for
+   * durability). Treat as an immutable snapshot.
+   */
+  readonly state: RunState;
+}
+//#endregion
+export { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent };
+//# sourceMappingURL=agent-event.d.ts.map

package/dist/types/agent-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event.d.ts","names":[],"sources":["../../src/types/agent-event.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/types/handoff.d.ts

@@ -0,0 +1,112 @@
+import { Message } from "./message.js";
+
+//#region src/types/handoff.d.ts
+
+/**
+ * Filter applied to the parent's message history when handing off control
+ * to a target agent. Implementations live in `@graphorin/agent` (e.g.
+ * `filters.lastN(10)`); the contract type lives here so every package
+ * (server, sessions, observability, …) can type a parameter as
+ * `HandoffFilter` without an agent dependency.
+ *
+ * The default for the agent runtime is `lastN(10)` (per the security-first
+ * compose policy). Filters should be **pure** — they receive a frozen
+ * history and return a fresh array.
+ *
+ * @stable
+ */
+type HandoffFilter = (history: readonly Message[]) => readonly Message[];
+/**
+ * Declarative handoff target. The value carries a reference to the target
+ * agent (`agentId` — looked up at runtime via the `AgentRegistry`) plus
+ * optional metadata used by the runtime when constructing the
+ * `transfer_to_<agentName>` virtual tool.
+ *
+ * @stable
+ */
+interface Handoff {
+  /** ID of the target agent (looked up via `AgentRegistry`). */
+  readonly targetAgentId: string;
+  /** Optional human-readable name, surfaced in the virtual tool name. */
+  readonly targetAgentName?: string;
+  /** Optional input filter applied to the parent's history. */
+  readonly inputFilter?: HandoffFilter;
+  /** Optional human-readable reason rendered in the audit log. */
+  readonly reason?: string;
+}
+/**
+ * Stable, serializable description of the input filter applied to a
+ * handoff. Persisted alongside `HandoffRecord` and round-tripped through
+ * the JSONL session export so a replay can re-construct the filter
+ * stack even after the runtime filter implementations evolve.
+ *
+ * The discriminator `kind` is an open string union — well-known kinds
+ * include `'full' | 'last-n' | 'last-user' | 'summary' |
+ * 'sensitivity-filter' | 'compose' | 'custom'`. The accompanying `meta`
+ * carries kind-specific data (for example `{ n: 10 }` for `'last-n'`,
+ * `{ summary: '...' }` for `'summary'`, or
+ * `{ messagesPassedCount, strippedReasoningCount, ... }` summary stats
+ * for `'compose'`). New kinds may be added freely; consumers must not
+ * assume an exhaustive switch.
+ *
+ * @stable
+ */
+interface HandoffInputFilterDescriptor {
+  readonly kind: string;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * How the parent's secrets surface is propagated to the sub-agent
+ * during a handoff. The default — `'inherit-allowlist'` with an empty
+ * inherited list — applies the principle of least authority: the sub-
+ * agent inherits only the keys the operator has explicitly named.
+ *
+ * - `'inherit-allowlist'` — inherit the keys named in
+ *   `inheritedSecrets`. Empty list = no inheritance.
+ * - `'isolated'` — the sub-agent runs with an empty secrets surface.
+ * - `'forward-explicit'` — every secret access on the sub-agent's side
+ *   must be explicitly broadened by the operator with a recorded
+ *   `secretsOverrideReason`.
+ *
+ * @stable
+ */
+type HandoffSecretsInheritance = 'inherit-allowlist' | 'isolated' | 'forward-explicit';
+/**
+ * Recorded handoff event captured on `RunState.handoffs` and replayed by
+ * the JSONL session export. The shape is wire-stable.
+ *
+ * @stable
+ */
+interface HandoffRecord {
+  readonly fromAgentId: string;
+  readonly toAgentId: string;
+  readonly stepNumber: number;
+  readonly at: string;
+  readonly reason?: string;
+  /**
+   * Serializable input-filter descriptor applied at handoff time. When
+   * undefined the runtime defaults applied (commonly
+   * `compose(lastN(10), stripReasoning, stripSensitiveOutputs)`); the
+   * concrete filter implementations live in `@graphorin/agent`.
+   */
+  readonly inputFilter?: HandoffInputFilterDescriptor;
+  /**
+   * Sub-agent secrets propagation policy. Defaults to
+   * `'inherit-allowlist'` with empty `inheritedSecrets`.
+   */
+  readonly secretsInheritance?: HandoffSecretsInheritance;
+  /**
+   * Keys inherited by the sub-agent under the
+   * `'inherit-allowlist'` / `'forward-explicit'` policies. Never the
+   * secret values themselves — only the public key names.
+   */
+  readonly inheritedSecrets?: ReadonlyArray<string>;
+  /**
+   * Operator-supplied justification for broadening or narrowing the
+   * default secrets surface. Surfaced in audit logs.
+   */
+  readonly secretsOverrideReason?: string;
+}
+//#endregion
+export { Handoff, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, HandoffSecretsInheritance };
+//# sourceMappingURL=handoff.d.ts.map

package/dist/types/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","names":[],"sources":["../../src/types/handoff.ts"],"sourcesContent":[],"mappings":";;;;;;AAeA;AAUA;AA4BA;AAoBA;AAQA;;;;;;;KAlEY,aAAA,sBAAmC,uBAAuB;;;;;;;;;UAUrD,OAAA;;;;;;yBAMQ;;;;;;;;;;;;;;;;;;;;;UAsBR,4BAAA;;kBAEC,SAAS;;;;;;;;;;;;;;;;;KAkBf,yBAAA;;;;;;;UAQK,aAAA;;;;;;;;;;;;yBAYQ;;;;;gCAKO;;;;;;8BAMF"}

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+import { SENSITIVITY_ORDER, Sensitivity, acceptsSensitivity } from "./sensitivity.js";
+import { Block, EntityRole, Episode, Fact, GraphEntity, Insight, MemoryHit, MemoryKind, MemoryMetadata, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, Rule } from "./memory.js";
+import { ToolCall } from "./tool-call.js";
+import { AssistantMessage, AudioContent, FileContent, ImageContent, Message, MessageContent, MessageRole, ReasoningContent, ReasoningContentMeta, SystemMessage, TextContent, ToolMessage, UserMessage } from "./message.js";
+import { SessionScope } from "./session-scope.js";
+import { Cost, ModelUsage, Usage, UsageAccumulator, UsageSnapshot, zeroUsage } from "./usage.js";
+import { Handoff, HandoffFilter, HandoffInputFilterDescriptor, HandoffRecord, HandoffSecretsInheritance } from "./handoff.js";
+import { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy } from "./tool.js";
+import { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunTaintSummary, flattenUsageByModel } from "./run.js";
+import { AgentCancellingEvent, AgentEndEvent, AgentErrorEvent, AgentEvaluatorConvergedEvent, AgentEvaluatorIterationEvent, AgentEvent, AgentFanOutMergedEvent, AgentFanOutSpawnedEvent, AgentFollowUpQueuedEvent, AgentLateralLeakDetectedEvent, AgentModelFellbackEvent, AgentProgressReadEvent, AgentProgressWrittenEvent, AgentResult, AgentStartEvent, AgentSteeredEvent, ContextCompactedEvent, FanOutChildMetadata, GuardrailTrippedEvent, HandoffEvent, LateralLeakVector, ProgressArtifactRef, ReasoningDeltaEvent, StepEndEvent, StepStartEvent, TextCompleteEvent, TextDeltaEvent, ToolApprovalDeniedEvent, ToolApprovalGrantedEvent, ToolApprovalRequestedEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecuteEndEvent, ToolExecuteErrorEvent, ToolExecutePartialEvent, ToolExecuteProgressEvent, ToolExecuteStartEvent } from "./agent-event.js";
+import { StopCondition, and, hasToolCall, isStepCount, isTerminal, not, or } from "./stop-condition.js";
+import { WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent } from "./workflow-event.js";
+export { type AgentCancellingEvent, type AgentEndEvent, type AgentErrorEvent, type AgentEvaluatorConvergedEvent, type AgentEvaluatorIterationEvent, type AgentEvent, type AgentFanOutMergedEvent, type AgentFanOutSpawnedEvent, type AgentFollowUpQueuedEvent, type AgentLateralLeakDetectedEvent, type AgentModelFellbackEvent, type AgentProgressReadEvent, type AgentProgressWrittenEvent, type AgentResult, type AgentStartEvent, type AgentSteeredEvent, type AssistantMessage, type AudioContent, type Block, type CompletedToolCall, type ContentChunk, type ContextCompactedEvent, type Cost, type EntityRole, type Episode, type Fact, type FanOutChildMetadata, type FileContent, type GraphEntity, type GuardrailTrippedEvent, type Handoff, type HandoffEvent, type HandoffFilter, type HandoffInputFilterDescriptor, type HandoffRecord, type HandoffSecretsInheritance, type ImageContent, type InboundSanitizationPolicy, type Insight, type LateralLeakVector, type MemoryGuardTier, type MemoryHit, type MemoryKind, type MemoryMetadata, type MemoryProvenance, type MemoryRecord, type MemorySearchOptions, type MemoryStatus, type Message, type MessageContent, type MessageRole, type ModelUsage, type ProgressArtifactRef, type ReasoningContent, type ReasoningContentMeta, type ReasoningDeltaEvent, type ResultHandle, type Rule, type RunContext, type RunError, type RunState, type RunStateUsageByModel, type RunStatus, type RunStep, type RunTaintSummary, SENSITIVITY_ORDER, type SandboxPolicy, type Sensitivity, type SessionScope, type SideEffectClass, type StepEndEvent, type StepStartEvent, type StopCondition, type SystemMessage, type TextCompleteEvent, type TextContent, type TextDeltaEvent, type ToolApproval, type ToolApprovalDeniedEvent, type ToolApprovalGrantedEvent, type ToolApprovalRequestedEvent, type ToolCall, type ToolCallDeltaEvent, type ToolCallEndEvent, type ToolCallStartEvent, type ToolError, type ToolErrorKind, type ToolExecuteEndEvent, type ToolExecuteErrorEvent, type ToolExecutePartialEvent, type ToolExecuteProgressEvent, type ToolExecuteStartEvent, type ToolMessage, type ToolOutcome, type ToolResult, type ToolSource, type ToolTrustClass, type TruncationStrategy, type Usage, type UsageAccumulator, type UsageSnapshot, type UserMessage, type WorkflowChannelUpdateEvent, type WorkflowCheckpointWrittenEvent, type WorkflowCustomEvent, type WorkflowEndEvent, type WorkflowErrorEvent, type WorkflowEvent, type WorkflowResumedEvent, type WorkflowStartEvent, type WorkflowStepEndEvent, type WorkflowStepStartEvent, type WorkflowSuspendedEvent, type WorkflowTaskEndEvent, type WorkflowTaskStartEvent, acceptsSensitivity, and, flattenUsageByModel, hasToolCall, isStepCount, isTerminal, not, or, zeroUsage };

package/dist/types/index.js

@@ -0,0 +1,6 @@
+import { flattenUsageByModel } from "./run.js";
+import { SENSITIVITY_ORDER, acceptsSensitivity } from "./sensitivity.js";
+import { and, hasToolCall, isStepCount, isTerminal, not, or } from "./stop-condition.js";
+import { zeroUsage } from "./usage.js";
+
+export { SENSITIVITY_ORDER, acceptsSensitivity, and, flattenUsageByModel, hasToolCall, isStepCount, isTerminal, not, or, zeroUsage };