Context Layer Types

declare interface ContextLayerShape<TState = unknown> {
  id: string;
  name?: string;
  slot: number;
  scope: ContextScope;
  budget?: BudgetConfig;
  hooks: ContextLayerHooks<TState>;
  timeouts?: Partial<LayerTimeouts>;
  onInitError?: 'throw' | 'disable';
  recallMode?: 'atomic' | 'eventual';
  provides?: unknown;
  itemSchemas?: unknown;
  rerenderTiming?: 'immediate' | 'batched';
  placement?: 'anchor' | 'live' | 'auto';
}

type LayerPlacement = 'anchor' | 'live' | 'auto';

type ContextScope = 'thread' | 'resource' | 'global' | 'execution';

type BudgetConfig =
  | number
  | { min: number; max: number }
  | 'auto';

const SlotShape = {
  REMINDER: 80,
  STEERING: 90,
  SCRATCHPAD: 100,
  ENTITY: 150,
  OBSERVATIONS: 200,
  PROCEDURAL: 250,
  EPISODIC: 300,
  RAG: 350,
  SEMANTIC_RECALL: 400,
} as const satisfies Record<string, number>;

interface ContextLayerHooks<TState = unknown> {
  init?: (params: InitParams) => Promise<InitResult<TState>>;
  recall?: (params: RecallParams<TState>) => Promise<RecallResult<TState> | string | null>;
  store?: (params: StoreParams<TState>) => Promise<StoreResult<TState> | undefined>;
  onSpawn?: (params: SpawnParams<TState>) => Promise<SpawnResult<TState> | null>;
  onReturn?: (params: ReturnParams<TState>) => Promise<ReturnResult<TState> | undefined>;
  onParentUpdate?: (params: ParentUpdateParams<TState>) => Promise<ParentUpdateResult<TState> | undefined>;
  onComplete?: (params: CompleteParams<TState>) => Promise<void | { state: TState }>;
  dispose?: (params: DisposeParams<TState>) => Promise<void>;
  beforeToolCall?: (params: BeforeToolCallParams<TState>) => Promise<BeforeToolCallResult<TState>>;
  afterModelCall?: (params: AfterModelCallParams<TState>) => Promise<AfterModelCallResult<TState>>;
  onSteer?: (params: OnSteerParams<TState>) => Promise<OnSteerResult<TState>>;
  onItemAppend?: (params: OnItemAppendParams<TState>) => Promise<OnItemAppendResult<TState>>;
  projectHistory?: (params: ProjectHistoryParams<TState>) => Promise<ProjectHistoryResult>;
  renderDelta?: (params: RenderDeltaParams<TState>) => Promise<string | null>;
  onDecision?: (params: OnDecisionParams<TState>) => Promise<undefined | { state: TState }>;
}

interface RecallOptions {
  peek?: boolean;
}

interface DecisionRecord {
  stepId: string;
  at: number;                     // epoch ms
  modelId: string;
  source: 'native' | 'estimated';
  answers: Readonly<Record<string, DecideAnswer>>;
}

type ExecutionOutcome = 'success' | 'failure' | 'aborted';

interface ExecutionContext {
  executionId: string;
  threadId: string;
  resourceId?: string;
  depth: number;
  stepNumber: number;
  tokenUsage: { input: number; output: number };
  cost: number;
  fs: FsAdapter;
  shell: ShellAdapter;
  callModel?: (request: LayerCallModelRequest) => Promise<LLMResponse>;
  tokenize(text: string): number;
  trace: {
    setAttribute(key: string, value: string | number | boolean): void;
    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
    createSpan?(name: string): ExecutionSpan;
  };
  readLayerState<T>(layerId: string): T | undefined;
}

interface ExecutionSpan {
  setAttribute(key: string, value: string | number | boolean): void;
  addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
  end(): Promise<void>; // ends the span and exports it
}

interface ProjectionPolicy {
  tokenBudget: number;
  responseReserve: number;
  overflow: 'truncate' | 'summarize' | 'sliding_window';
  overflowModel?: string;
  windowSize?: number;
}

interface ContextCacheConfig {
  enabled?: boolean;
  minCachedTokens?: number;
  minEpochAssemblies?: number;
  maxEpochAssemblies?: number;
  deltaBudgetFraction?: number;
  autoDemoteChurn?: number;
  autoPromoteChurn?: number;
  minChurnSamples?: number;
  churnDecay?: number;
}

type ReanchorReason =
  | 'cold-start'
  | 'instructions-changed'
  | 'cache-miss'
  | 'delta-pressure'
  | 'delta-overflow'
  | 'max-age';

interface StorageAdapter {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix: string): Promise<string[]>;
}

interface ScopedStorage {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix?: string): Promise<string[]>;
}

interface LayerStateStore {
  get<T>(executionId: string, layerId: string): T | undefined;
  set<T>(executionId: string, layerId: string, state: T): void;
  cleanup(executionId: string): void;
  diagnostic: (layerId: string, hook: string, error: unknown) => void;
  // Optional — implemented by createLayerStateStore(); custom stores may omit them.
  has?(executionId: string, layerId: string): boolean;
  registerDurable?(executionId: string, layerId: string, target: ScopedStorage): void;
  flush?(executionId: string): Promise<void>;
  disable?(executionId: string, layerId: string): void;
  isDisabled?(executionId: string, layerId: string): boolean;
}

interface LayerTraceSpan {
  layerId: string;
  hook:
    | 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onParentUpdate' | 'onComplete'
    | 'dispose' | 'onDecision' | 'beforeToolCall' | 'afterModelCall' | 'projectHistory' | 'onItemAppend'
    | 'onSteer';
  duration: number;
  status: 'ok' | 'error' | 'timeout' | 'skipped';
  budget?: { allocated: number; used: number; yielded: number };
  itemCount?: number;
  error?: { message: string; stack?: string };
}

type ContextData = Readonly<Record<string, Record<string, unknown>>>;

interface ContextConfig<TLayers extends ContextLayer[] = ContextLayer[]> {
  layers: TLayers;
  _shape: InferContextShape<TLayers>;
}

type InferContext<T extends { readonly _shape: unknown }> = T['_shape'];

type LayerProvides = Record<string, LayerDataDecl | LayerFunctionDecl>;

interface LayerDataDecl<T = unknown, TState = unknown> {
  kind: 'data';
  read: (state: TState) => T;
}

interface LayerFunctionDecl<TInput = unknown, TOutput = unknown, TState = unknown> {
  kind: 'function';
  description: string;
  input: ZodType<TInput>;
  output: ZodType<TOutput>;
  execute(args: TInput, state: TState, ctx: ExecutionContext): Promise<{ result: TOutput; state?: TState }>;
}

function layerData<T, TState>(opts: {
  read: (state: TState) => T;
}): LayerDataDecl<T, TState>;

function layerFunction<TInput, TOutput, TState>(opts: {
  description: string;
  input: ZodType<TInput>;
  output: ZodType<TOutput>;
  execute: (
    args: TInput,
    state: TState,
    ctx: ExecutionContext,
  ) => Promise<{ result: TOutput; state?: TState }>;
}): LayerFunctionDecl<TInput, TOutput, TState>;

function context<const T extends readonly ContextLayer[]>(layers: T): ContextConfig<T>;