export interface AgentClientOptions {
  serverUrl: string;
  agentKey: string;
  onDisconnect?: (close: CloseInfo) => void;
  onReconnect?: (helloOk: ConnectResult) => void;
}

export interface ChannelCoreOptions {
  service: ChannelService;
  dispatchAdmissionTimeoutMs?: number;
}

export interface ChannelService {
  readonly ownAgentId: string | undefined;
  on(
    event: "message",
    handler: (payload: { taskId: TaskId; message: Message }) => void,
  ): void;
  on(event: "disconnect", handler: () => void): void;
  on(event: "reconnect", handler: () => void): void;
  on(
    event: "conversationArchived",
    handler: (data: { conversationId: string }) => void,
  ): void;
  on(
    event: "conversationUnarchived",
    handler: (data: { conversationId: string }) => void,
  ): void;
  on(
    event: "dispatchRelease",
    handler: (frame: DispatchReleaseFrame) => void,
  ): void;
  connect(): Effect.Effect<unknown, ServiceRpcError>;
  close(): void;
  send(
    taskId: TaskId,
    conversationId: ConversationId,
    text: string,
    opts?: { replyTo?: MessageId; dispatchLeaseId?: LeaseId },
  ): Effect.Effect<void, ServiceRpcError>;
  isConversationArchived?(conversationId: string): boolean;
  getConversation(
    convId: string,
  ): { type: string; name?: string; participants: string[] } | undefined;
  getAgentName(agentId: string): string | undefined;
  resolveAgentName(agentId: string): Effect.Effect<string, never>;
  peekContextEntries(
    currentConvId: string,
    opts?: { maxConversations?: number; maxMessagesPerConv?: number },
  ): { entries: CrossConversationEntry[]; commit: () => void };
  peekFullMessages(currentConvId: string): {
    messages: CrossConvMessage[];
    commit: () => void;
  };

  /**
   * Issue `dispatch/request` and receive the immediate
   * `{leaseId, dispatchId}` ack. The verdict arrives asynchronously
   * via the `dispatchRelease` event.
   *
   * The argument shape mirrors `ParamsOf&lt;DispatchRequest>` from the
   * protocol (the channel core does not depend on the protocol
   * descriptor, hence the structural shape duplicated here).
   *
   * Optional: when undefined (e.g. unauthenticated test fakes), the
   * channel core falls back to default-grant — every inbound message
   * dispatches without admission.
   */
  requestDispatch?(params: {
    readonly conversationId: string;
    readonly messageId: string;
    readonly senderAgentId: string;
    readonly parts?: ReadonlyArray<unknown>;
    readonly receivedAt?: string;
    readonly pending?: ReadonlyArray<unknown>;
    readonly clock?: LogicalClock;
    readonly attempt?: number;
  }): Effect.Effect<
    { readonly leaseId: LeaseId; readonly dispatchId: string },
    ServiceRpcError
  >;
}

export interface ContextBlocks {
  groupMetadata?: EnrichedConversationMeta;
  crossConversation?: CrossConversationEntry[];
  crossConversationMessages?: CrossConvMessage[];
}

export interface ContextOptions {
  type: "cross-conversation";
  maxConversations?: number;
  maxMessagesPerConv?: number;
}

export interface ConversationMeta {
  id: string;
  type: string;
  name?: string;
  participants: string[];
}

export interface CrossConversationEntry {
  conversationId: string;
  conversationName?: string;
  senderName: string;
  text: string;
  minutesAgo: number;
  /** Messages in this summary (capped by maxMessagesPerConv). */
  count: number;
}

export interface CrossConvMessage {
  conversationId: string;
  conversationName?: string;
  senderName: string;
  senderId: string;
  text: string;
  timestamp: string;
}

export type DispatchAdmissionDecision =
  | {
      _tag: "grant";
      leaseId?: LeaseId;
      leaseTimeoutMs?: number;
      dispatchMessageId?: string;
    }

export interface DispatchAdmissionRequest {
  message: Message;
  conversationId: string;
  senderAgentId: string;
  attempt: number;
  receivedAt: string;
  clock: LogicalClock;
  pending: ReadonlyArray<PendingDispatchMessage>;
}

export interface DispatchReleaseFrame {
  readonly dispatchId: string;
  readonly leaseId: LeaseId;
  readonly verdict:
    | {
        readonly decision: "grant";
        readonly leaseId?: LeaseId;
        readonly leaseTimeoutMs?: number;
        readonly dispatchMessageId?: string;
      }
    | { readonly decision: "deny"; readonly reason?: string }
    | { readonly decision: "hold"; readonly reason?: string };
  readonly leaseTimeoutMs?: number;
}

export function drainPaginatedList<
  E,
  D extends RpcDefinition<string, any, any>,
  K extends keyof ResultOf<D>,
>(
  sendRpc: SendRpcFn<E>,
  definition: D,
  collectionKey: K,
): Effect.Effect<ResultOf<D>[K], E | NonAdvancingCursorError>

export interface EnrichedConversationMeta {
  type: "dm" | "group";
  name?: string;
  /** "type:id" strings (e.g. "agent:uuid"). */
  participants: string[];
}

export interface EnrichedInboundMessage {
  id: string;
  taskId: TaskId;
  conversationId: ConversationId;
  sender: EnrichedSender;
  /** Text parts joined with newlines. Non-text parts dropped. */
  text: string;
  isFromMe: boolean;
  createdAt: string;
  replyToId?: string;
  conversationMeta?: EnrichedConversationMeta;
  contextBlocks: ContextBlocks;

  /**
   * Present when multiple queued messages from the same conversation were
   * coalesced into this single dispatch. Includes the primary message first.
   */
  coalescedMessages?: ReadonlyArray<{
    id: string;
    sender: EnrichedSender;
    text: string;
    createdAt: string;
    replyToId?: string;
  }>;
  /** Lease that authorizes a runtime reply for this dispatch, when present. */
  dispatchLeaseId?: LeaseId;
}

export interface EnrichedSender {
  id: string;
  name: string;
}

export function formatCrossConversationBlock(
  entries: CrossConversationEntry[],
  opts: { header: string },
): string | null

export type InboundHandler<E = unknown> = (
  msg: EnrichedInboundMessage,
) => Effect.Effect<void, E>;

export class MoltZapAgentClient {
  private readonly stateRef: Ref.Ref<Option.Option<ConnState>>;
  private readonly malformedRef: Ref.Ref<number>;
  private readonly runtime: ManagedRuntime.ManagedRuntime<
    Socket.WebSocketConstructor,
    never
  >;
  private readonly subscribers: SubscriberRegistry;
  private closed = false;
  private reconnectFiber: Fiber.RuntimeFiber<void, never> | null = null;
  private _helloOk: ConnectResult | null = null;

  constructor(private readonly options: AgentClientOptions) {
    this.runtime = ManagedRuntime.make(NodeSocket.layerWebSocketConstructor);
    this.stateRef = this.runtime.runSync(
      Ref.make<Option.Option<ConnState>>(Option.none()),
    );
    this.malformedRef = this.runtime.runSync(Ref.make(0));
    this.subscribers = this.runtime.runSync(makeSubscriberRegistry());
  }

  get helloOk(): ConnectResult | null {
    return this._helloOk;
  }

  connect(): Effect.Effect<ConnectResult, ConnectError> {
    return this.runtime.runtimeEffect.pipe(
      Effect.flatMap(() => this.connectEffect()),
      Effect.provide(this.runtime),
    );
  }

  /**
   * Outbound RPC. The compile-time constraint accepts any
   * `RpcDefinition` so generic forwarders (service.sendRpc, CLI
   * transport) can pass through without per-method narrowing; the R11
   * agent-client catalog narrowing applies at runtime inside
   * `AgentClientConnection` and rejects TM-only methods.
   */
  sendRpc<D extends RpcDefinition<string, any, any>>(
    definition: D,
    params: ParamsOf<D>,
    opts?: RpcCallOptions,
  ): Effect.Effect<ResultOf<D>, ConnectError> {
    const timeoutMs = opts?.timeoutMs ?? RPC_TIMEOUT_MS;
    return this.sendRpcEffect(definition, params, timeoutMs);
  }

  subscribe<D extends AnyNotificationDefinition>(
    definition: D,
    refinement?: (params: NotificationParamsOf<D>) => boolean,
  ): Stream.Stream<DecodedNotification<D>, NotConnectedError, never>;
  subscribe<
    D extends AnyNotificationDefinition,
    R extends NotificationParamsOf<D>,
  >(
    definition: D,
    refinement: (params: NotificationParamsOf<D>) => params is R,
  ): Stream.Stream<DecodedNotification<D, R>, NotConnectedError, never>;
  subscribe<D extends AnyNotificationDefinition>(
    definition: D,
    // eslint-disable-next-line agent-code-guard/no-conditional-chaining -- optional refinement is a value-level passthrough to the Stream factory; not a refinement-of-discriminant decision
    refinement?: (params: NotificationParamsOf<D>) => boolean,
  ): Stream.Stream<DecodedNotification<D>, NotConnectedError, never> {
    return subscribeStream(this.subscribers, definition, refinement);
  }

  subscribeAll(
    // eslint-disable-next-line agent-code-guard/no-conditional-chaining -- optional refinement is a value-level passthrough to the Stream factory; not a refinement-of-discriminant decision
    refinement?: (
      notification: DecodedNotification<AnyNotificationDefinition>,
    ) => boolean,
  ): Stream.Stream<
    DecodedNotification<AnyNotificationDefinition>,
    NotConnectedError,
    never
  > {
    return subscribeAllStream(this.subscribers, refinement);
  }

  close(): Effect.Effect<void, never> {
    return Effect.gen(this, function* () {
      if (this.closed) return;
      const hasCompletedHandshake = this._helloOk !== null;
      this.closed = true;
      this._helloOk = null;
      if (this.reconnectFiber !== null) {
        const f = this.reconnectFiber;
        this.reconnectFiber = null;
        yield* Effect.forkDaemon(Fiber.interrupt(f));
      }
      yield* this.failAllPending(MSG_NOT_CONNECTED);
      yield* this.subscribers.closeAll;
      const state = yield* Ref.getAndSet(this.stateRef, Option.none());
      if (Option.isSome(state)) {
        if (hasCompletedHandshake) {
          yield* state.value
            .write(new Socket.CloseEvent(NORMAL_CLOSE_CODE, "normal"))
            .pipe(Effect.orDie);
          yield* Scope.close(state.value.scope, Exit.void);
        } else {
          this.runtime.runFork(Scope.close(state.value.scope, Exit.void));
        }
      }
    }).pipe(
      Effect.asVoid,
      Effect.ensuring(
        Effect.sync(() => {
          this.runtime.dispose();
        }),
      ),
    );
  }

  disconnect(): Effect.Effect<void, never> {
    return Effect.sync(() => this.disconnectSync());
  }

  private disconnectSync(): void {
    const state = this.runtime.runSync(Ref.get(this.stateRef));

export class MoltZapChannelCore {
  private readonly service: ChannelService;
  private readonly dispatchAdmissionTimeoutMs: number;
  private connected = false;
  private inboundHandler: InboundHandler<unknown> | null = null;

  /**
   * Lease id scoped to the in-flight `dispatchInboundEffect` call
   * (set immediately around the user-handler invocation). Replaces
   * the legacy `activeDispatchLeaseId` field whose semantics were
   * unchanged but whose name leaked an admission-flow detail. The
   * field remains a single mutable cell because the consumer fiber
   * processes inbound work strictly serially (one queue, one fiber);
   * concurrent dispatches do not exist on this code path.
   */
  private leaseIdInFlight: LeaseId | undefined;

  /**
   * Per-lease parking Deferreds for dispatches awaiting their
   * `dispatchRelease` verdict. Settled by the `dispatchRelease` event
   * handler when a matching frame arrives.
   */
  private readonly pendingDispatchesByLease = new Map<
    string,
    Deferred.Deferred<DispatchReleaseFrame, never>
  >();

  /**
   * Ring buffer of `dispatchRelease` frames that arrived before the
   * recipient registered its parking Deferred (release-then-ack
   * race). Bounded LRU via Map insertion-order iteration; soft-TTL
   * eviction at `DISPATCH_RELEASE_RING_SOFT_TTL_MS` so a release
   * without a matching ack does not leak memory.
   */
  private readonly pendingReleasesByLease = new Map<
    string,
    PendingReleaseEntry
  >();
  private readonly closedConversationIds = new Set<string>();
  private readonly logicalClocks = new Map<
    string,
    { epoch: number; vector: Record<string, number> }
  >();
  private readonly parkedByConversation = new Map<
    string,
    InboundDispatchWork[]
  >();

  /**
   * Inbound messages enqueue synchronously; a single forked consumer fiber
   * serialises delivery so handlers execute one-at-a-time in arrival order.
   */
  private readonly inboundQueue: Queue.Queue<InboundDispatchWork> =
    Effect.runSync(Queue.unbounded<InboundDispatchWork>());
  private readonly consumerFiber: Fiber.RuntimeFiber<void, never>;
  private disconnectHandlers: Array<() => void> = [];
  private reconnectHandlers: Array<() => void> = [];

  constructor(opts: ChannelCoreOptions) {
    this.service = opts.service;
    this.dispatchAdmissionTimeoutMs =
      opts.dispatchAdmissionTimeoutMs ?? DEFAULT_DISPATCH_ADMISSION_TIMEOUT_MS;

    this.registerMessageListener();
    this.consumerFiber = this.startConsumerFiber();
    this.registerConnectionListeners();
    this.registerConversationLifecycleListeners();
    this.registerDispatchReleaseListener();
  }

  private registerMessageListener(): void {
    this.service.on("message", ({ taskId, message }) => {
      if (this.closedConversationIds.has(message.conversationId)) {
        runBackgroundLog(
          effectLogInfo(
            "MoltZapChannelCore: dropping inbound message for closed conversation",
            {
              messageId: message.id,
              conversationId: message.conversationId,
            },
          ),
        );
        return;
      }
      Queue.unsafeOffer(this.inboundQueue, {
        taskId,
        message,
        attempt: 0,
        receivedAtMs: Date.now(),
        clock: this.observeMessage(message),
      });
    });
  }

  private startConsumerFiber(): Fiber.RuntimeFiber<void, never> {
    const consumer = Effect.forever(
      Queue.take(this.inboundQueue).pipe(
        Effect.flatMap((work) =>
          this.dispatchInboundWork(work).pipe(
            Effect.catchAllCause((cause) =>
              this.logInboundFailure(work, cause),
            ),
          ),
        ),
      ),
    );
    return Effect.runFork(consumer);
  }

  private logInboundFailure(
    work: InboundDispatchWork,
    cause: Cause.Cause<unknown>,
  ): Effect.Effect<void, never> {
    return effectLogError("MoltZapChannelCore: inbound handler failed", {
      messageId: work.message.id,
      conversationId: work.message.conversationId,
      causePretty: Cause.pretty(cause),
      ...errorSummary(Cause.squash(cause)),
    });
  }

export class MoltZapService {
  private client: MoltZapAgentClient | null = null;
  private _connected = false;

  /**
   * Service-owned scope (spec #596 / Spec B §"4.2 service.ts" lifecycle
   * reshape). Opened in `connect()`, owns the `subscribeAll → Stream.runForEach`
   * fan-out fiber. Closed in `close()` so the fiber terminates with the
   * service.
   *
   * Held off the public `connect()` signature so callers do not need to
   * thread a `Scope` requirement.
   */
  private serviceScope: Scope.CloseableScope | null = null;

  private readonly conversationsRef: Ref.Ref<
    HashMap.HashMap<string, ConversationMeta>
  > = Effect.runSync(Ref.make(HashMap.empty<string, ConversationMeta>()));
  private readonly messagesRef: Ref.Ref<
    HashMap.HashMap<string, ReadonlyArray<Message>>
  > = Effect.runSync(Ref.make(HashMap.empty<string, ReadonlyArray<Message>>()));
  private readonly agentNamesRef: Ref.Ref<HashMap.HashMap<string, string>> =
    Effect.runSync(Ref.make(HashMap.empty<string, string>()));
  private readonly agentConversationCacheRef: Ref.Ref<
    HashMap.HashMap<
      string,
      { readonly taskId: TaskId; readonly conversationId: ConversationId }
    >
  > = Effect.runSync(
    Ref.make(
      HashMap.empty<
        string,
        { readonly taskId: TaskId; readonly conversationId: ConversationId }
      >(),
    ),
  );
  private readonly lastNotifiedRef: Ref.Ref<
    HashMap.HashMap<string, HashMap.HashMap<string, string>>
  > = Effect.runSync(
    Ref.make(HashMap.empty<string, HashMap.HashMap<string, string>>()),
  );
  private readonly lastReadRef: Ref.Ref<
    HashMap.HashMap<string, HashMap.HashMap<string, ReadonlySet<string>>>
  > = Effect.runSync(
    Ref.make(
      HashMap.empty<string, HashMap.HashMap<string, ReadonlySet<string>>>(),
    ),
  );
  private readonly archivedConversationIds = new Set<string>();

  /**
   * Insertion-ordered set of recently seen messageIds per conversation.
   * Bounded at DEDUP_WINDOW_PER_CONV entries per conversation; oldest entry
   * is evicted when the window is full. Set#keys() preserves insertion
   * order in V8 / the spec, so eviction via `.next()` is O(1).
   *
   * Keyed and valued by their branded ids so the compiler rejects a
   * `MessageId` accidentally used as a conversation key (or vice versa).
   */
  private readonly seenMessageIds = new Map<ConversationId, Set<MessageId>>();
  private readonly handlers: {
    [K in ServiceHandlerName]: Array<
      NotificationHandler<ServiceHandlerPayloads[K]>
    >;
  } = {
    message: [],
    rawNotification: [],
    disconnect: [],
    reconnect: [],
    conversationArchived: [],
    conversationUnarchived: [],
    dispatchRelease: [],
    dispatchesConsumed: [],
    dispatchesExpired: [],
  };
  private readonly notificationDispatchers = new Map<
    AnyNotificationDefinition,
    NotificationDispatcher
  >([
    [
      MessageReceivedNotificationDefinition,
      (notification) =>
        this.handleMessageReceivedNotification(
          notification.params as MessageReceivedNotification,
        ),
    ],
    [
      TaskConversationCreatedNotificationDefinition,
      (notification) =>
        this.handleConversationCreatedNotification(
          notification.params as TaskConversationCreatedNotification,
        ),
    ],
    [
      TaskConversationArchivedNotificationDefinition,
      (notification) =>
        this.handleConversationArchivedNotification(
          notification.params as TaskConversationArchivedNotification,
        ),
    ],
    [
      TaskConversationUnarchivedNotificationDefinition,
      (notification) =>
        this.handleConversationUnarchivedNotification(
          notification.params as TaskConversationUnarchivedNotification,
        ),
    ],
    [
      DispatchRelease,
      (notification) =>
        fanout(
          this.handlers.dispatchRelease,
          notification.params as NotificationParamsOf<typeof DispatchRelease>,
        ),
    ],
    [
      DispatchesConsumed,
      (notification) =>
        fanout(
          this.handlers.dispatchesConsumed,

export class MoltZapTMClient {
  private readonly stateRef: Ref.Ref<Option.Option<ConnState>>;
  private readonly malformedRef: Ref.Ref<number>;
  private readonly runtime: ManagedRuntime.ManagedRuntime<
    Socket.WebSocketConstructor,
    never
  >;

  /**
   * Per-subscription notification registry. Spec #596 / Spec B: callback-based
   * storage feeds `Stream.async` consumers via `notification/stream.ts`.
   */
  private readonly subscribers: SubscriberRegistry;

  /**
   * Spec F (#617) immutable TM-callback handler table. Captured from
   * `TMClientOptions.handlers` at construction and threaded through
   * every `makeTaskMasterConnection` call (including reconnects).
   */
  private readonly handlers: TMHandlers;

  private closed = false;
  private reconnectFiber: Fiber.RuntimeFiber<void, never> | null = null;
  private _helloOk: ConnectResult | null = null;

  constructor(private readonly options: TMClientOptions) {
    this.runtime = ManagedRuntime.make(NodeSocket.layerWebSocketConstructor);
    this.stateRef = this.runtime.runSync(
      Ref.make<Option.Option<ConnState>>(Option.none()),
    );
    this.malformedRef = this.runtime.runSync(Ref.make(0));
    this.subscribers = this.runtime.runSync(makeSubscriberRegistry());
    this.handlers = options.handlers;
  }

  get helloOk(): ConnectResult | null {
    return this._helloOk;
  }

  /**
   * Open the socket, perform `network/connect`, resolve with HelloOk.
   * Fails immediately on pre-open close or error.
   *
   * ```mermaid
   * sequenceDiagram
   *   participant caller
   *   participant client as MoltZapTMClient
   *   participant server
   *
   *   caller->>client: new MoltZapTMClient(options)
   *   Note over client: stateRef = None, subscribers, ManagedRuntime
   *   caller->>client: subscribe(filter, handler)
   *   Note over client: SubscriberRegistry.register — survives reconnect
   *   caller->>client: connect()
   *   Note over client: connectEffect — Scope.make, Socket.makeWebSocket open<br>startTaskCallbackDispatcher — bounded Queue 8192 + drain<br>readerFiber = runFork(readerEffect)
   *   client->>server: TCP open + WS upgrade
   *   client->>server: network/connect {agentKey, minProtocol, maxProtocol}
   *   server-->>client: HelloOk
   *   Note over client: stateRef = Some(connState), _helloOk = value
   *   client-->>caller: HelloOk
   *   Note over client,server: steady state — reader fiber loops on socket.runRaw
   * ```
   *
   * Reconnect arm fires from `handleReaderExit` when the reader fiber
   * exits with `closed === false`. `failAllPending` settles every
   * in-flight Deferred with `NotConnectedError`, `notifyDisconnect`
   * surfaces the close info, then `scheduleReconnect` forks an
   * exponential-backoff retry (`1s × 2^n, cap 30s, +jitter`).
   *
   * State that SURVIVES reconnect: `SubscriberRegistry` entries,
   * `appCallbackHandlers` (immutable, value-captured at construction),
   * `ManagedRuntime`.
   *
   * State that does NOT survive reconnect: in-flight RPC Deferreds
   * (failed via `failAllPending`), the prior `ConnState` (scope,
   * reader fiber, callback queue, dispatcher scope) — rebuilt fresh.
   */
  connect(): Effect.Effect<ConnectResult, ConnectError> {
    return Effect.suspend(() => {
      if (this.closed) {
        return Effect.fail(makeNotConnectedError());
      }
      return this.connectEffect().pipe(
        // `makeWebSocket` requires `Socket.WebSocketConstructor`; our
        // internal Node layer provides it so callers' Effects stay
        // requirement-free (same public shape the legacy client had).
        Effect.provide(NodeSocket.layerWebSocketConstructor),
      );
    });
  }

  /**
   * Send an RPC. Fails with a typed error:
   *   - `NotConnectedError` if the socket isn't OPEN or closes mid-RPC
   *   - `RpcTimeoutError` after `RPC_TIMEOUT_MS` — no automatic retry
   *   - a registered tagged error for known protocol error codes
   *   - `RpcServerError` for unknown protocol error codes
   *
   * Descriptor-backed RPC call. Callers pass the protocol descriptor, and the
   * client extracts the wire method only inside the encoder path.
   */
  sendRpc<D extends RpcDefinition<string, any, any>>(
    definition: D,
    params: ParamsOf<D>,
    opts?: RpcCallOptions,
  ): Effect.Effect<ResultOf<D>, ConnectError> {
    const timeoutMs = opts?.timeoutMs ?? RPC_TIMEOUT_MS;
    return this.sendRpcEffect(definition, params, timeoutMs);
  }

  /**
   * Typed-payload subscribe (spec #596 Goal #1). Returns a Stream of
   * `DecodedNotification<D>` whose error channel is `NotConnectedError`
   * and whose requirement set is `never`.
   *
   * `refinement` is a typed predicate over the definition's params shape.
   * The user-defined-type-guard overload (signature below) narrows the
   * Stream's payload to `DecodedNotification<D, R>`.
   *
   * Lifecycle (spec §"Stream lifecycle contract"):

export class NonAdvancingCursorError extends Data.TaggedError(
  "NonAdvancingCursorError",
)<{
  readonly method: string;
}> {
  override get message(): string {
    return `Pagination cursor for ${this.method} did not advance — refusing to loop`;
  }
}

export interface PendingDispatchMessage {
  messageId: string;
  conversationId: string;
  senderAgentId: string;
  createdAt: string;
  receivedAt: string;
  clock?: LogicalClock;
  parts?: Message["parts"];
}

export const registerAgent = (
  baseUrl: string,
  name: string,
  opts: RegisterAgentOptions = {},
): Effect.Effect<RegisterResponse, RegisterAgentError>

export interface RegisterAgentOptions {
  description?: string;
  inviteCode?: string;

  /**
   * When set, registers via the secret-gated admin endpoint and pre-claims
   * the agent for this user. See {@link registerAgent}.
   */
  ownerUserId?: string;
}

export interface RegisterResponse {
  agentId: string;
  apiKey: string;
  claimUrl: string;
  claimToken: string;
}

export interface RpcCallOptions {
  readonly timeoutMs?: number;
}

export function sanitizeForSystemReminder(s: string): string

export type SendRpcFn<E> = <D extends RpcDefinition<string, any, any>>(
  definition: D,
  params: ParamsOf<D>,
) => Effect.Effect<ResultOf<D>, E>;

export interface ServiceOptions {
  serverUrl: string;
  agentKey: string;
}

export type ServiceRpcError = RpcCallError | RpcTimeoutError;

export interface ConversationMeta {
  id: string;
  type: string;
  name?: string;
  participants: string[];
}

export interface TaskCallbackContext {
  readonly requestId: JsonRpcId;
}

export interface TMClientOptions {
  serverUrl: string;
  agentKey: string;

  /**
   * Called once per disconnect (not reconnect). Spec #222 §5.4 + OQ-5 (A):
   * `close` is the typed close metadata — real WebSocket `{code, reason}`
   * when the transport surfaces them, OQ-5 defaults otherwise.
   *
   * Migration note (spec #596): the previous `subscribe(filter, handler)` /
   * `waitForNotification` / `notificationsBufferRef` surface was deleted in
   * Spec B. Callers consume notifications via `subscribe(def, refinement?)`
   * returning a `Stream`, or `subscribeAll(refinement?)` for the broad-union
   * escape hatch.
   */
  onDisconnect?: (close: CloseInfo) => void;
  onReconnect?: (helloOk: ConnectResult) => void;

  /**
   * Spec D3 R14b — REQUIRED. TM-callback handler table immutable at
   * construction (Spec F I1). Keys are catalog method names
   * (`"dispatch/authorize"`, `"messages/authorize"`); each value carries
   * the matching `defineRpc` descriptor and its handler effect.
   * Vacuous-deny moderators write the explicit ForbiddenError handler.
   */
  handlers: TMHandlers;
}

export type TMHandlers = TaskMasterHandlers<TaskCallbackContext>;