// Copyright (c) 2026 Hellmai Ltd
// SPDX-License-Identifier: AGPL-3.0-only
//
// WU-2732 (INIT-060 Phase 3, ADR-013 §6 governance surface):
// Port interface for the six remote-control tools. Both the mock
// tracer-bullet adapter (this WU) and the real kernel-side adapter
// (WU-2733) implement this port — so the real impl lands without
// changing the wire contract. This mirrors ADR-013's ChannelBridge
// port pattern (single port, multiple adapters).

import type { AbortTurnInvocationResult, RemoteControlInvocationResult } from './types.js';

/**
 * Minimum input shape every remote-control tool accepts. The session
 * identifier is the load-bearing field: it pins which agent-runtime
 * session the command targets. Real impls in WU-2733 will extend this
 * with per-tool specific fields (e.g. autonomy level for elevate);
 * extensions MUST be additive to preserve the wire contract.
 */
export interface RemoteControlInvocationInput {
  session_id?: string;
}

export interface AbortTurnInvocationInput extends RemoteControlInvocationInput {
  /**
   * Operator-supplied reason surfaced in the emitted
   * `agent-runtime:turn_aborted` event in the real impl. The mock
   * tracer-bullet records this for round-trip verification but does
   * not emit the event (WU-2733 wires the real emission per
   * ADR-013 §1 abort table).
   */
  reason?: string;
}

/**
 * Remote-control port. The six methods correspond 1:1 to the six
 * manifest-declared tool names. Keeping them as separate methods (not
 * a single `invoke(name, input)` dispatcher) lets TypeScript enforce
 * per-tool input/output types at the call site.
 */
export interface RemoteControlPort {
  resumeWorkflow(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
  pauseTurn(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
  abortTurn(input: AbortTurnInvocationInput): Promise<AbortTurnInvocationResult>;
  elevateAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
  lowerAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
  approveInflight(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
}
