hosted-execution-authority.ts

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import type { BackendStopMode } from '@maka/core/backend-types';
import type { RootExecutionDescriptor } from '@maka/core/runtime-invocation';
import type { MessageContent, SessionEvent } from '@maka/core/events';
import type { UserMessageInput } from '@maka/core/runtime-inputs';
import type { StopSessionInput } from '@maka/runtime/session-manager';
import type { TurnSnapshot } from '../protocol/index.js';

export interface HostedExecutionRef {
  readonly sessionId: string;
  readonly turnId: string;
  readonly runId: string;
}

export interface HostedExecutionAdmission extends HostedExecutionRef {
  readonly userMessageId: string | null;
  readonly execution: RootExecutionDescriptor;
  readonly content: MessageContent | null;
  readonly turnOrchestration?: UserMessageInput['turnOrchestration'];
  readonly admitExecution?: () => Promise<'executing' | 'cancelled'>;
  readonly start: (input: {
    readonly runId: string;
    readonly userMessageId: string | null;
    readonly onRunStarted: () => void | Promise<void>;
  }) => AsyncIterable<SessionEvent>;
  readonly onEvent?: (event: SessionEvent) => void;
  readonly onReady?: () => void | Promise<void>;
}

export type HostedExecutionSnapshot = TurnSnapshot;

export interface HostedExecutionIdentity extends HostedExecutionRef {
  readonly userMessageId: string | null;
  readonly descriptor: RootExecutionDescriptor;
}

export type HostedExecutionCompletion =
  | {
      readonly kind: 'terminal';
      readonly snapshot: HostedExecutionSnapshot;
    }
  | {
      readonly kind: 'authority_error';
      readonly execution: HostedExecutionRef;
      readonly reason: string;
    };

export interface HostedExecutionObservation extends HostedExecutionRef {
  readonly descriptor: RootExecutionDescriptor;
}

export type HostedExecutionCompletionObserver = (
  completion: HostedExecutionCompletion,
) => void | Promise<void>;

export interface HostedExecutionAdmissionResult {
  readonly snapshot: HostedExecutionSnapshot;
  readonly completion: Promise<HostedExecutionCompletion>;
  readonly settled: Promise<void>;
}

export interface HostedExecutionObserver {
  begin(input: HostedExecutionObservation): HostedExecutionCompletionObserver | undefined;
}

export type HostedExecutionStopInput = {
  readonly execution: HostedExecutionRef;
} & StopSessionInput;

export type HostedExecutionListener = (execution: HostedExecutionRef) => void;

export interface HostedExecutionPreparedAdmission {
  readonly sessionId: string;
  admit(input: HostedExecutionAdmission): Promise<HostedExecutionAdmissionResult>;
  release(): void;
}

export type HostedExecutionPreparation =
  | {
      readonly kind: 'prepared';
      readonly admission: HostedExecutionPreparedAdmission;
    }
  | {
      readonly kind: 'busy';
      readonly whenIdle: Promise<void>;
      readonly execution?: HostedExecutionRef;
    }
  | { readonly kind: 'unavailable'; readonly reason: string };

export interface HostedExecutionAuthority {
  prepare(sessionId: string): HostedExecutionPreparation;
  admit(input: HostedExecutionAdmission): Promise<HostedExecutionAdmissionResult>;
  lookup(sessionId: string, turnId: string): Promise<HostedExecutionIdentity | undefined>;
  read(execution: HostedExecutionRef): Promise<HostedExecutionSnapshot>;
  requestStop(input: HostedExecutionStopInput): Promise<HostedExecutionSnapshot>;
  reconcile(execution: HostedExecutionRef): Promise<HostedExecutionSnapshot>;
  subscribe(listener: HostedExecutionListener): () => void;
  /** Same-Epoch availability hint. Durable reconciliation must not depend on this promise. */
  whenIdle(sessionId: string): Promise<void> | undefined;
  runExclusiveSessionOperation<T>(
    input: {
      readonly sessionId: string;
      readonly abortSignal: AbortSignal;
      readonly stopSource?: Exclude<HostedExecutionStopInput['source'], 'workhub_direct_stop'>;
    },
    operation: () => Promise<T>,
  ): Promise<T>;
}

export function isHostedExecutionTerminal(snapshot: HostedExecutionSnapshot): boolean {
  return (
    snapshot.status === 'completed' ||
    snapshot.status === 'failed' ||
    snapshot.status === 'cancelled'
  );
}

export function completedHostedExecutionAdmission(
  snapshot: HostedExecutionSnapshot,
): HostedExecutionAdmissionResult {
  return Object.freeze({
    snapshot,
    completion: Promise.resolve<HostedExecutionCompletion>({
      kind: 'terminal',
      snapshot,
    }),
    settled: Promise.resolve(),
  });
}