Durable Sessions

import {
  session,
  getSession,
  type Session,
  type SessionFor,
  type SessionForTarget,
  type SessionOptions,
  type FlowSessionOptions,
  type SessionTurnHandle,
  type SessionStatus,
  type SessionInspection,
  type SessionSubscription,
  type SessionEvent,
  type SessionStreamOptions,
  type SessionRuntimeReadModel,
  SessionIdentityConflictError,
  SessionNotFoundError,
  SessionInputError,
  SessionCapabilityError,
  SessionClosedError,
  SessionDeletedError,
  SessionLifecycleError,
  SessionNotClosedError,
  SessionTombstonedError,
  GenerationModelBindingError,
  GenerationModelNotStaticError,
  GenerationModelCapabilityError,
} from "@use-crux/core";

// equivalent focused surface
import { session, getSession } from "@use-crux/core/session";

// Agent
function session<TAgent extends AnyAgent, TModel extends GenerationModel | undefined>(
  target: TAgent,
  options: SessionOptions<TAgent, TModel> & SessionModelGuard<TAgent, TModel>,
): Promise<SessionForTarget<TAgent>>;

// Flow
function session<TFlow extends AnyFlowTarget>(
  target: TFlow,
  options: FlowSessionOptions,
): Promise<SessionForTarget<TFlow>>;

function getSession<TTarget extends SessionTarget>(
  target: TTarget,
  key: string,
): Promise<SessionForTarget<TTarget>>;

type SessionOptions<A extends AnyAgent, M extends GenerationModel | undefined> = {
  readonly key: string;
} & (
  | { readonly model?: M } // when Agent already has a GenerationModel
  | { readonly model: M } // when Agent has no GenerationModel
);

type FlowSessionOptions = {
  readonly key: string;
};

interface Session<TInput, TOutput = unknown> {
  readonly id: string;
  readonly thread: SessionThreadView;
  readonly forkedFrom?: SessionForkLineage;
  send(input: TInput): Promise<SessionTurnHandle<TOutput>>;
  sendMany(
    inputs: readonly TInput[],
  ): Promise<readonly SessionTurnHandle<TOutput>[]>;
  status(): Promise<SessionStatus>;
  inspect(): Promise<SessionInspection>;
  stats(): Promise<ExecutionStats>;
  stream(options?: SessionStreamOptions): AsyncIterable<SessionEvent>;
  close(): Promise<void>;
  kill(): Promise<void>;
  delete(): Promise<void>;
  fork(): Promise<this>;
  clone(): Promise<this>;
  forks(): Promise<readonly SessionForkSummary[]>;
}

// Agent and Flow handles also carry:
//   targetKind: "agent" | "flow"
//   subscribe / subscriptions (Signal surface)

interface SessionThreadView {
  readonly id: string;
  read(options?: ThreadReadOptions): Promise<ThreadSnapshot>;
}

interface SessionInputHandle {
  readonly id: string;
  readonly cursor: string;
  readonly acceptedAt: Date;
}

interface SessionTurnHandle<TOutput> extends SessionInputHandle {
  work(): Promise<WorkHandle<TOutput>>;
  result(): Promise<TOutput>;
}

interface SessionSubscription {
  readonly id: string;
  readonly signalId: string;
  readonly matchKey: string;
  readonly state: "active" | "unsubscribed";
  unsubscribe(): Promise<void>;
}

// on Session handles that include the subscription surface:
subscribe(source: Signal | MatchFilter): Promise<SessionSubscription>;
subscriptions(): Promise<readonly SessionSubscription[]>;

interface SessionStreamOptions {
  readonly after?: string;
}

type SessionEvent =
  | { type: "session.snapshot"; reason: "initial" | "cursor-expired"; status: SessionStatus; /* … */ }
  | { type: "session.status"; status: SessionStatus; /* … */ }
  | { type: "ingress.accepted"; ingress: SessionIngressSummary; /* … */ }
  | { type: "ingress.delivered"; ingress: SessionIngressSummary; stepIndex: number; workId?: string; /* … */ };

interface SessionStatus {
  readonly state: "parked" | "running" | "blocked" | "closing" | "closed";
  readonly acceptedCursor?: string;
  readonly processedCursor?: string;
  readonly pendingInputs: number;
  readonly pendingWork: number;
}

interface SessionInspection {
  readonly id: string;
  readonly targetId: string;
  readonly threadId: string;
  readonly wakePending: boolean;
  readonly inputs: readonly SessionInputInspection[];
  readonly checkpoint?: SessionCheckpointInspection;
  readonly recovery?: SessionRecoveryDiagnostic;
  readonly coverage: { readonly inputs: "complete" | "truncated"; readonly limit: 64 };
}

interface SessionRuntimeReadModel {
  readonly schema: 1;
  readonly identity: {
    readonly sessionId: string;
    readonly keyHash: string;
    readonly targetId: string;
    readonly targetKind: "agent" | "flow";
    readonly threadId: string;
  };
  readonly status: SessionStatus;
  readonly wakePending: boolean;
  readonly activation?: { readonly inputId: string; readonly workId: string };
  readonly forkedFrom?: SessionForkLineage;
  readonly thread: { readonly revision: string };
  readonly subscriptions: readonly SessionRuntimeSubscription[];
  readonly inputs: readonly SessionRuntimeInput[];
  readonly checkpoint?: SessionRuntimeCheckpoint;
  readonly recovery?: SessionRecoveryDiagnostic;
  readonly coverage: { readonly inputs: "complete" | "truncated"; readonly limit: 64 };
  readonly stats: ExecutionStats;
}

import { runSessionConformanceTests } from "@use-crux/core/runtime/testing";