AgentHarness Types

declare interface HarnessApi<TParams extends Record<string, unknown> = Record<string, unknown>> {
  readonly config: AgentConfig<TParams>;
  readonly fs: FsAdapter;
  readonly shell: ShellAdapter;
  readonly subprocess: SubprocessAdapter;
  readonly rootCwdState: { cwd: string; previousCwd?: string };

  callModel(request: CallModelRequest): Promise<LLMResponse>;
  decide(request: DecideRequest): Promise<DecideResponse>;
  execute(input: ExecuteInput, options?: ExecuteOptions): Promise<void>;
  getAgentResponse(scope?: SessionScope): Promise<HarnessResponse>;
  getItemStream(scope?: SessionScope): AsyncIterable<StreamingItem>;
  getTextStream(scope?: SessionScope): AsyncIterable<string>;
  getReasoningStream(scope?: SessionScope): AsyncIterable<string>;
  getFullStream(scope?: SessionScope): AsyncIterable<StreamEvent>;
  abort(scope?: SessionScope & CancelOptions): Promise<DrainReport | undefined>;
  getStatus(scope: ExecutionScope): ExecutionStatus;
  getStatus(scope?: SessionScope): HarnessStatus;
  getQueueSize(scope?: SessionScope): number;
  seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
  setRootCwd(nextCwd: string): void;

  run<I, O>(step: Step<ContextData, I, O>, input: I, ctx: Context): Promise<O>;
  detachedSpawn<I, O>(
    step: Step<ContextData, I, O>,
    input: I,
    parentCtx: Context,
    overrides?: { threadId?: string; resourceId?: string; cwdInit?: string },
  ): DetachedHandle<O>;
  createContext(opts?: {
    parent?: Context;
    items?: Item[];
    state?: unknown;
    threadId?: string;
    resourceId?: string;
    contextLayers?: ContextLayer[];
    cwdInit?: string;
  }): Context;

  send<T>(channel: Channel<T>, value: NoInfer<T>, ctx: Context): Promise<void>;
  recv<T>(channel: Channel<T>, ctx: Context, opts?: { timeout?: number }): Promise<T>;
  tryRecv<T>(channel: Channel<T>, ctx: Context): T | null;
  getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
  getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;

  initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
  recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
  recallLayersAtomic(
    layers: ContextLayer[],
    input: string,
    ctx: Context,
    budgets: Map<string, number>,
    opts?: RecallOptions,
  ): Promise<RecallLayerOutput[]>;
  recallLayersEventual(
    layers: ContextLayer[],
    input: string,
    ctx: Context,
    budgets: Map<string, number>,
    opts?: RecallOptions,
  ): Promise<RecallLayerOutput[]>;
  projectHistory(
    layers: ContextLayer[],
    items: ReadonlyArray<Item>,
    ctx: Context,
  ): Promise<ReadonlyArray<Item>>;
  runAppendPipeline(
    layers: ContextLayer[],
    items: Item[],
    ctx: Context,
  ): Promise<{ items: Item[]; rerenderRequests: RerenderRequest[] }>;
  executeRerender(
    requests: RerenderRequest[],
    layers: ContextLayer[],
    ctx: Context,
    budgets: Map<string, number>,
    query?: string,
  ): Promise<RecallLayerOutput[]>;
  previewRequestItems(scope?: SessionScope): Promise<ReadonlyArray<Item>>;
  storeLayers(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<void>;
  disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
  getLayerState<T>(executionId: string, layerId: string): T | undefined;
  setLayerState<T>(executionId: string, layerId: string, state: T): void;

  beforeToolCall(
    layers: ContextLayer[],
    toolName: string,
    toolArgs: unknown,
    ctx: Context,
  ): Promise<unknown>;
  afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<unknown>;
  notifyDecision(layers: ContextLayer[], record: DecisionRecord, ctx: Context): Promise<void>;

  checkpoint(ctx: Context): Promise<void>;
  restore(executionId: string): Promise<Context | null>;
  cancel(ctx: Context, options?: string | CancelOptions): Promise<DrainReport | undefined>;
  createSpan(name: string, parent: Span | null): Span;
}

declare interface RerenderRequest {
  layerId: string;
  slot: number;
  timing: 'immediate' | 'batched';
  scope: 'self' | 'slot-after' | 'all';
}

type DeliveryMode = 'next-turn' | 'between-rounds' | 'next-item' | 'interrupt';

interface ExecuteOptions {
  threadId?: string;
  resourceId?: string;
  state?: unknown;
  contextLayers?: ContextLayer[];
  deliveryMode?: DeliveryMode;
  messageId?: string;
}

interface SessionScope {
  threadId?: string;
}

type HarnessStatus =
  | { readonly kind: 'idle' }
  | { readonly kind: 'generating'; readonly startedAt: number; readonly turnId: string }
  | { readonly kind: 'draining'; readonly turnId: string; readonly deadline: number }
  | { readonly kind: 'aborting'; readonly turnId: string };

interface ExecutionScope {
  executionId: string; // a root context's id
}

type ExecutionStatus =
  | { readonly kind: 'idle' }
  | { readonly kind: 'generating'; readonly startedAt: number }
  | { readonly kind: 'draining'; readonly deadline: number }
  | { readonly kind: 'aborting' };

interface CancelOptions {
  readonly reason?: string;
  /** Let in-flight model calls finish for up to this many ms before cancelling. */
  readonly drainMs?: number;
}

interface DrainReport {
  readonly executionId: string;
  readonly reason: 'settled' | 'deadline' | 'stopped';
  readonly durationMs: number;
  readonly finished: ReadonlyArray<DrainCall>;
  readonly cutOff: ReadonlyArray<DrainCall>;
}

interface DrainCall {
  readonly kind: 'model_round' | 'decide';
  readonly model: string;
  readonly executionId: string; // the context that made the call
  readonly round?: number;
  readonly dispatchId?: string;
  readonly generationId?: string;
  readonly cost?: number;
  readonly usage?: RoundUsage;
}

interface HarnessResponse {
  readonly items: ReadonlyArray<Item>;
  readonly usage: { inputTokens: number; outputTokens: number; cachedTokens?: number };
  readonly cost?: number;       // USD the turn's work cost, replayed work included
  readonly billedCost?: number; // USD the turn actually paid — 0 for replayed work
  readonly heldCost?: number;   // USD held for cut-off paid calls with no settled bill yet
  readonly text: string;
  readonly lastLayerUsage?: LastLayerUsage;
}

type StreamEvent = SdkStreamEvent | FrameworkStreamEvent;

interface SdkStreamEvent {
  readonly source: 'sdk';
  readonly type: string;
  readonly data: Record<string, unknown>;
  readonly outputIndex?: number;
  readonly contentIndex?: number;
}

interface FrameworkStreamEvent {
  readonly source: 'framework';
  readonly type: `${string}:${string}`;
  readonly data: Record<string, unknown>;
}

type StreamingItem = Item & { readonly isComplete: boolean };

declare interface AgentConfigShape<
  TParams extends Record<string, unknown> = Record<string, unknown>,
> {
  name: string;
  storage?: StorageAdapter;
  hooks?: AgentHooks;
  params: TParams;
  itemSchemas?: { schemas?: unknown; strict?: boolean };
  projection?: ProjectionPolicy;
  forceAtomicRecall?: boolean;
  contextCache?: unknown;
  decisionModel?: string;
  emitItemsOnReplay?: boolean;
  approveToolCall?: ToolApprover;
}

interface DecideRequest {
  model: string;
  instructions?: string;
  state: ReadonlyArray<DecideStatePart>;
  questions: DecideQuestions;
  samples?: number;
  signal?: AbortSignal;
}

type DecideStatePart =
  | { type: 'text'; text: string; name?: string }
  | { type: 'json'; name: string; value: unknown }
  | { type: 'image'; imageUrl: string };

interface DecideResponse {
  answers: Readonly<Record<string, DecideAnswer>>;
  source: 'native' | 'estimated';
  modelId: string;
  usage: { inputTokens: number; outputTokens: number };
  cost?: number;
}

interface AgentHooks {
  beforeStep?: (step: Step, ctx: Context) => Promise<void>;
  afterStep?: (step: Step, result: unknown, ctx: Context) => Promise<void>;
}

interface DetachedHandle<O> {
  readonly id: string;
  readonly status: DetachedStatus;
  readonly result: O | undefined;
  readonly error: string | undefined;
  await(timeout?: number): Promise<O>;
}

const DetachedStatus = {
  Running: 'running',
  Completed: 'completed',
  Failed: 'failed',
} as const;
type DetachedStatus = (typeof DetachedStatus)[keyof typeof DetachedStatus];

interface RecallLayerOutput {
  layerId: string;
  items: Item[];
  tokenCount: number;
  mutatedState?: boolean;
}

interface RoundUsage {
  inputTokens: number;
  outputTokens: number;
  cachedTokens?: number;
  cacheWriteTokens?: number;
}

interface LLMResponse {
  items: Item[];
  usage: RoundUsage;
  rounds?: ReadonlyArray<RoundUsage>;
  cost?: number;
  billedCost?: number;
  recall?: boolean;
}